Export Logs From a CockroachDB Standard Cluster

Perform the following steps to enable log export from your CockroachDB Standard cluster to Amazon CloudWatch.

1. Create the desired target Amazon CloudWatch log group by following the Create a log group in CloudWatch logs instructions. If you already have a log group created, you can skip this step. To send logs to more than one target log group, refer to the custom configuration option in step 8.

2. Find your CockroachDB Standard cluster ID:

   1. Visit the CockroachDB Cloud console cluster page.
   2. Click on the name of your cluster.
   3. Find your cluster ID in the URL of the single cluster overview page: https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview.

3. Determine your cluster's cloud provider account ID. This command uses the third-party JSON parsing tool jq to isolate just the needed aws_account_id field:

   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/{your_cluster_id} \
     --header 'Authorization: Bearer {secret_key}' | jq .keychain_config.aws_account_id
   

   Where:

   • {your_cluster_id} is the cluster ID of your CockroachDB Standard cluster as determined in step 2.
   • {secret_key} is your CockroachDB Standard API key. Refer to API Access for more details.

4. Create a cross-account IAM role in your AWS account:

   1. In the AWS console, visit the IAM page.
   2. Select Roles and click Create role.
   3. For Trusted entity type, select AWS account.
   4. Choose Another AWS account.
      1. For Account ID, provide the CockroachDB Standard cloud provider account ID from step 3.
      2. Select the option to Require external ID, and for the value of External ID, provide the cluster ID of your CockroachDB Standard cluster as determined in step 2.
   5. Finish creating the IAM role with a suitable name. These instructions will use the role name CockroachCloudLogExportRole. You do not need to add any permissions.
   Note:

   You will need the Amazon Resource Name (ARN) for your cross-account IAM role later in this procedure.

5. Select the new role, and create a new policy for this role. These instructions will use the policy name CockroachCloudLogExportPolicy.

6. Select the new policy, and paste the following into the Permissions tab, with the {} JSON option selected:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Action": [
                   "logs:CreateLogGroup",
                   "logs:CreateLogStream",
                   "logs:DescribeLogGroups",
                   "logs:DescribeLogStreams",
                   "logs:PutRetentionPolicy",
                   "logs:PutLogEvents"
               ],
               "Effect": "Allow",
               "Resource": [
                   "arn:aws:logs:*:{your_aws_acct_id}:log-group:{log_group_name}:*"
               ]
           }
       ]
   }
   

   Where:

   • {your_aws_acct_id} is the AWS Account ID of the AWS account where you created the CockroachCloudLogExportRole role, not the AWS Account ID of your CockroachDB Standard cluster. You can find your AWS Account ID on the AWS IAM page.
   • {log_group_name} is the target Amazon CloudWatch log group you created in step 1.

   This defines the set of permissions that the CockroachDB Standard log export feature requires to be able to write logs to CloudWatch.

   If desired, you may also limit log export from your CockroachDB Standard cluster to a specific single AWS region, by providing the name of the desired region as the fourth value to the Resource entry. For example:

   "Resource": [
       "arn:aws:logs:us-east-1:{your_aws_acct_id}:log-group:{log_group_name}:*"
   ]
   

   Specifying an AWS region that you do not have a cluster in, or a region that only partially covers your cluster will result in missing logs.

7. Copy the Amazon Resource Name (ARN) of the CockroachCloudLogExportRole role found under Summary, which is needed for the next step.

8. Use one of the following Cloud API commands to enable log export for your CockroachDB Standard cluster. The first presents a basic configuration, where all logs are sent to Amazon CloudWatch using the default settings. The second allows for more detailed customization of the logging configuration, such as the ability to send certain log channels to specific target log groups, or the ability to redact sensitive log entries.

   1. To enable log export for your CockroachDB Standard cluster with default logging configuration, issue the following Cloud API command:

      curl --request POST \
        --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
        --header "Authorization: Bearer {secret_key}" \
        --data '{"type": "AWS_CLOUDWATCH", "log_name": "{log_group_name}", "auth_principal": "{role_arn}"}'
      

      Where:

      • {cluster_id} is your CockroachDB Standard cluster ID as determined in step 2.
      • {secret_key} is your CockroachDB Standard API key. Refer to API Access for instructions on generating this key.
      • {log_group_name} is the target Amazon CloudWatch log group you created in step 1.
      • {role_arn} is the ARN for the CockroachCloudLogExportRole role you copied in step 7.

   2. To enable log export for your CockroachDB Standard cluster with custom logging configuration:

      1. Consult the log export entry on the CockroachDB Cloud API Reference and select the Schema tab to view the supported log configuration options, and determine the customized logging configuration you would like to use.

         For example, consider the following configuration:

         {
          "type": "AWS_CLOUDWATCH",
          "log_name": "default",
          "auth_principal": "{role_arn}",
          "redact": true,
          "region": "",
          "omitted_channels": [ "SESSIONS", "SQL_PERF"],
          "groups": [
                  {
                      "log_name": "sql",
                      "channels": ["SQL_SCHEMA", "SQL_EXEC"],
                      "redact": false
                  },
                  {
                      "log_name": "devops",
                      "channels": ["OPS", "HEALTH", "STORAGE"],
                      "min_level": "WARNING"
                  }
          ]
         }
         

         This configuration:

         • Enables redaction globally for all log entries emitted to AWS CloudWatch.
         • Does not send log entries in the SESSIONS and SQL_PERF logging channels.
         • Sends log entries in the SQL_SCHEMA and SQL_EXEC logging channels to a AWS CloudWatch log group named sql, and overrides (disables) the global redaction configuration for just these two log channels only.
         • Sends log entries in the OPS, HEALTH, and STORAGE logging channels to an AWS CloudWatch log group named devops, but only for those entries that are of log severity level WARNING or higher.
         • Sends log entries in all other logging channels to the default AWS CloudWatch log group.

      2. Once you have determined the configuration you'd like to use, edit the configuration to be a single line, the required form for passing to the configuration command in the next step. To accomplish this easily, use a third-party minifier, such as json minifier. The preceding configuration becomes the following single line:

         {"type":"AWS_CLOUDWATCH","log_name":"default","auth_principal":"{role_arn}","redact":true,"region":"","omitted_channels":["SESSIONS","SQL_PERF"],"groups":[{"log_name":"sql","channels":["SQL_SCHEMA","SQL_EXEC"],"redact":false},{"log_name":"devops","channels":["OPS","HEALTH","STORAGE"],"min_level":"WARNING"}]}
         

      3. To enable log export for your CockroachDB Standard cluster with the preceding example configuration, issue the following Cloud API command:

         curl --request POST \
           --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
           --header "Authorization: Bearer {secret_key}" \
           --data '{"type":"AWS_CLOUDWATCH","log_name":"default","auth_principal":"{role_arn}","redact":true,"region":"","omitted_channels":["SESSIONS","SQL_PERF"],"groups":[{"log_name":"sql","channels":["SQL_SCHEMA","SQL_EXEC"],"redact":false},{"log_name":"devops","channels":["OPS","HEALTH","STORAGE"],"min_level":"WARNING"}]}'
         

         Where:

         • {cluster_id} is your CockroachDB Standard cluster ID as determined in step 2.
         • {secret_key} is your CockroachDB Standard API key. Refer to API Access for instructions on generating this key.
         • {role_arn} is the ARN for the CockroachCloudLogExportRole role you copied in step 7.

9. Depending on the size of your cluster and how many regions it spans, the configuration may take a moment. You can monitor the ongoing status of the configuration using the following Cloud API command:

   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
     --header "Authorization: Bearer {secret_key}"
   

   Run the command periodically until the command returns a status of ENABLED, at which point the configuration is complete, and logs will begin appearing in CloudWatch under the log group you created in step 1. Since the configuration is applied to cluster regions in a rolling fashion, you may see some logs appear even before the GET command returns an ENABLED status.

10. Once log export has been enabled, you can access logs from your CockroachDB Standard cluster directly in Amazon CloudWatch.

Perform the following steps to enable log export from your CockroachDB Standard cluster to GCP Cloud Logging.

1. Find your CockroachDB Standard organization ID in the CockroachDB Cloud organization information page.

2. Find your CockroachDB Standard cluster ID:

   1. Visit the CockroachDB Cloud console cluster page.
   2. Click on the name of your cluster.
   3. Find your cluster ID in the URL of the single cluster overview page: https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview.

3. Determine the GCP principal to grant permission to from your account. This principal is already created for you by Cockroach Labs; this step merely determines its account name. This command uses the third-party JSON parsing tool jq to isolate just the needed id (GCP cluster ID) and account_id (GCP account ID) fields, and combines them for you in the required form:

   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/{your_cluster_id} \
     --header 'Authorization: Bearer {secret_key}' | jq .keychain_config.gcp_auth_principal
   

   Where:

   • {your_cluster_id} is the cluster ID of your CockroachDB Standard cluster as determined in step 2.
   • {secret_key} is your API access key. Refer to API Access for more details.

   The resulting GCP principal should resemble the following example:

   CRLKeychainServiceAccount@crl-staging-1abc.iam.gserviceaccount.com
   

   This GCP principal refers to a resource that is owned by Cockroach Labs and is created automatically along with your cluster. You do not need to create this account in GCP; it is already present for use by your cluster.

4. Create a new role with the required permissions in your GCP project:

   1. In the GCP console, visit the IAM roles page for your project.
   2. Click + Create role.
   3. Give your role a title and ID of your choosing, then click + Add permissions.
   4. Search for logging.logEntries.create in the Filter field, check the checkbox next to the resulting match, then click Add.
   5. Click the Create button.

5. Create a new service account in your GCP project:

   1. In the GCP console, visit the Service Accounts page for your project.
   2. Click + CREATE SERVICE ACCOUNT.
   3. Give your service account a name and ID of your choosing, then click CREATE AND CONTINUE.
   4. For the Grant this service account access to project step, select the role you created in Step 4.
   5. Click the DONE button.

6. Give permissions to the new service account.

   1. Click into the new service account you created in step 5.
   2. Under DETAILS, copy the email address for the service account.
   3. Click PERMISSIONS.
   4. Click + GRANT ACCESS.
   5. Under Add principals, enter the GCP principal from step 3.
   6. Under Assign roles, select "Service Account Token Creator".

7. Use one of the following Cloud API commands to enable log export for your CockroachDB Standard cluster. The first presents a basic configuration, where all logs are sent to GCP Cloud Logging using the default settings. The second allows for more detailed customization of the logging configuration, such as the ability to send certain log channels to specific target log groups, or the ability to redact sensitive log entries.

   1. To enable log export for your CockroachDB Standard cluster with default logging configuration, issue the following Cloud API command:

      curl --request POST \
        --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
        --header "Authorization: Bearer {secret_key}" \
        --data '{"type": "GCP_CLOUD_LOGGING", "log_name": "{log_name}", "auth_principal": "{service_account_email}"}'
      

      Where:

      • {cluster_id} is your CockroachDB Standard cluster ID as determined in step 2.
      • {secret_key} is your CockroachDB Standard API key. Refer to API Access for instructions on generating this key.
      • {log_name} is a string of your choosing to represent logs written from your CockroachDB Standard cluster. This name will appear in the name of each log written to GCP Cloud Logging.
      • {service_account_email} is the email address of the service account that you copied in step 6.

   2. To enable log export for your CockroachDB Standard cluster with custom logging configuration:

      1. Consult the log export entry on the CockroachDB Cloud API Reference and select the Schema tab to view the supported log configuration options, and determine the customized logging configuration you would like to use.

         For example, consider the following configuration:

         {
          "type": "GCP_CLOUD_LOGGING",
          "log_name": "default",
          "auth_principal": "{service_account_email}",
          "redact": true,
          "region": "",
          "omitted_channels": [ "SESSIONS", "SQL_PERF"],
          "groups": [
                  {
                      "log_name": "sql",
                      "channels": ["SQL_SCHEMA", "SQL_EXEC"],
                      "redact": false
                  },
                  {
                      "log_name": "devops",
                      "channels": ["OPS", "HEALTH", "STORAGE"],
                      "min_level": "WARNING"
                  }
          ]
         }
         

         This configuration:

         • Enables redaction globally for all log entries emitted to GCP Cloud Logging.
         • Does not send log entries in the SESSIONS and SQL_PERF logging channels.
         • Sends log entries in the SQL_SCHEMA and SQL_EXEC logging channels to a GCP Cloud Logging log group named sql, and overrides (disables) the global redaction configuration for just these two log channels only.
         • Sends log entries in the OPS, HEALTH, and STORAGE logging channels to a GCP Cloud Logging log group named devops, but only for those entries that are of log severity level WARNING or higher.
         • Sends log entries in all other logging channels to the default GCP Cloud Logging log group.

      2. Once you have determined the configuration you'd like to use, edit the configuration to be a single line, the required form for passing to the configuration command in the next step. To accomplish this easily, use a third party minifier, such as json minifier. The preceding configuration becomes the following single line:

         {"type":"GCP_CLOUD_LOGGING","log_name":"default","auth_principal":"{service_account_email}","redact":true,"region":"","omitted_channels":["SESSIONS","SQL_PERF"],"groups":[{"log_name":"sql","channels":["SQL_SCHEMA","SQL_EXEC"],"redact":false},{"log_name":"devops","channels":["OPS","HEALTH","STORAGE"],"min_level":"WARNING"}]}
         

      3. To enable log export for your CockroachDB Standard cluster with the preceding example configuration, issue the following Cloud API command:

         curl --request POST \
           --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
           --header "Authorization: Bearer {secret_key}" \
           --data '{"type":"GCP_CLOUD_LOGGING","log_name":"default","auth_principal":"{service_account_email}","redact":true,"region":"","omitted_channels":["SESSIONS","SQL_PERF"],"groups":[{"log_name":"sql","channels":["SQL_SCHEMA","SQL_EXEC"],"redact":false},{"log_name":"devops","channels":["OPS","HEALTH","STORAGE"],"min_level":"WARNING"}]}'
         

         Where:

         • {cluster_id} is your CockroachDB Standard cluster ID as determined in step 2.
         • {secret_key} is your CockroachDB Standard API key. Refer to API Access for instructions on generating this key.
         • {service_account_email} is the email address of the service account that you copied in step 6.

8. Depending on the size of your cluster and how many regions it spans, the configuration may take a moment. You can monitor the ongoing status of the configuration using the following Cloud API command:

   curl --request GET \
     --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
     --header "Authorization: Bearer {secret_key}"
   

   Run the command periodically until the command returns a status of ENABLED, at which point the configuration is complete, and logs will begin appearing in GCP Cloud Logging. Since the configuration is applied to cluster regions in a rolling fashion, you may see some logs appear even before the GET command returns an ENABLED status.

9. Once log export has been enabled, you can access logs from your CockroachDB Standard cluster directly in GCP Cloud Logging's Log Explorer.