> ## Documentation Index > Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Export Logs From a CockroachDB Advanced Cluster export const InternalLink = ({version, path = "", children, ...props}) => { let detectedVersion = version || "stable"; if (typeof window !== 'undefined' && !version) { const match = window.location.pathname.match(/\/docs\/([^/]+)/); if (match) { detectedVersion = match[1]; } } const normalizedPath = path.startsWith("/") ? path.slice(1) : path; return {children} ; }; export const version = "stable"; CockroachDB Advanced users can use the Cloud API to configure log export to [Amazon CloudWatch](https://aws.amazon.com/cloudwatch), [GCP Cloud Logging](https://cloud.google.com/logging), [Azure Monitor](https://learn.microsoft.com/azure/azure-monitor/logs/data-platform-logs), or any destination that accepts the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/) over HTTP. Once the export is configured, logs will flow from all nodes in all regions of your CockroachDB Advanced cluster to your chosen log sink. You can configure log export to redact sensitive log entries, limit log output by severity, send log entries to specific log group targets by log channel, and more. Log exports include the cluster name (`cloud_cluster_name`) in addition to the cluster ID (`cloud_cluster_id`), which makes it easier to identify logs from specific clusters. ## The `logexport` endpoint To configure and manage log export for your CockroachDB Advanced cluster, use the `logexport` endpoint: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} https://cockroachlabs.cloud/api/v1/clusters/{your_cluster_id}/logexport ``` Access to the `logexport` endpoint requires a valid CockroachDB Cloud service account assigned one of the following roles: * Organization Admin * Cluster Admin * Cluster Operator * Metrics Viewer The following methods are available for use with the `logexport` endpoint: | Method | Description | | -------- | ------------------------------------------------------------------------------------------------------ | | `GET` | Returns the current status of the log export configuration. | | `POST` | Enables log export, or updates an existing log export configuration. | | `DELETE` | Disables log export, halting all log export to Amazon CloudWatch, GCP Cloud Logging, or Azure Monitor. | ## Log name format GCP Cloud Logging and AWS CloudWatch logs have the following name format: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} {log-name}.{region}.cockroachdbcloud.{log-channel}.n{N} ``` Where: * {'{log-name}'} is a string of your choosing as you configure log export. For Amazon CloudWatch, this is the [log group](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams#Create-Log-Group) you create as part of enabling log export. For GCP Cloud Logging, this is the `log_name` you choose during configuration. Refer to the [Enable log export](#enable-log-export) instructions specific to your cloud provider for more information. * {'{region}'} is the cloud provider region where your CockroachDB Advanced cluster resides. * {'{log-channel}'} is the CockroachDB log channel, such as `HEALTH` or `OPS`. * {'{N}'} is the node number of the CockroachDB Advanced node emitting the log messages. Log messages received before a node is fully started may appear in a log named without an explicit node number, ending in just `.n`. For Azure Monitor, the logs have a different name format, refer to Enable log export - Verify instructions. ## Enable log export Perform the following steps to enable log export from your CockroachDB Advanced cluster to Amazon CloudWatch. 1. Create the desired target Amazon CloudWatch log group by following the [Create a log group in CloudWatch logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams#Create-Log-Group) 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 Advanced cluster ID: 1. Visit the CockroachDB Cloud console [cluster page](https://cockroachlabs.cloud/clusters). 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 CockroachDB Advanced cluster's associated AWS Account ID. This command uses the third-party JSON parsing tool [`jq`](https://stedolan.github.io/jq/download) to isolate just the needed `account_id` field from the results: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{your_cluster_id} \ --header "Authorization: Bearer {secret_key}" | jq .account_id ``` Refer to API Access for instructions on generating the {'{secret_key}'}. 4. Create a cross-account IAM role in your AWS account: 1. In the AWS console, visit the [IAM page](https://console.aws.amazon.com/iam). 2. Select **Roles** and click **Create role**. 3. For **Trusted entity type**, select **AWS account**. 4. Choose **Another AWS account**. 5. For **Account ID**, provide the CockroachDB Advanced AWS Account ID from step 3. 6. 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. 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: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "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 Advanced cluster. You can find your AWS Account ID on the AWS [IAM page](https://console.aws.amazon.com/iam). * {'{log_group_name}'} is the target Amazon CloudWatch log group you created in step 1. This defines the set of permissions that the CockroachDB Advanced log export feature requires to be able to write logs to CloudWatch. If desired, you may also limit log export from your CockroachDB Advanced 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: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} "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's nodes will result in missing logs. 7. Copy the [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces) 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 Advanced 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 Advanced cluster with **default** logging configuration, issue the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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 Advanced cluster ID as determined in step 2. * {'{secret_key}'} is your CockroachDB Advanced 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 Advanced 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: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "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 Amazon 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 Amazon 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 Amazon 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](#what-log-channels-are-supported) to the `default` Amazon 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](https://jsonformatter.org/json-minify). The preceding configuration becomes the following single line: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} {"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 Advanced cluster with the preceding example configuration, issue the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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 Advanced cluster ID as determined in step 2. * {'{secret_key}'} is your CockroachDB Advanced 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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 across all nodes 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 nodes 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 Advanced cluster directly in [Amazon CloudWatch](https://console.aws.amazon.com/cloudwatch/home). Perform the following steps to enable log export from your CockroachDB Advanced cluster to GCP Cloud Logging. 1. Find your CockroachDB Advanced organization ID in the CockroachDB Cloud [organization information page](https://cockroachlabs.cloud/information). 2. Find your CockroachDB Advanced cluster ID: 1. Visit the CockroachDB Cloud console [cluster page](https://cockroachlabs.cloud/clusters). 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`](https://stedolan.github.io/jq/download) 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{your_cluster_id} \ --header "Authorization: Bearer {secret_key}" | jq '("crl-logging-user-" + (.id | split("-"))[4] + "@" + .account_id + ".iam.gserviceaccount.com")' ``` Where: * {'{your_cluster_id}'} is the cluster ID of your CockroachDB Advanced 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: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} crl-logging-user-a1c42be2e53b@crl-prod-abc.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](https://console.cloud.google.com/iam-admin/roles) 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. Add your cluster's GCP principal to the role you just created. 1. In the GCP console, visit the [IAM admin page](https://console.cloud.google.com/iam-admin) for your project. 2. Click the **+ Grant Access** button. 3. In the box labeled **New principals**, enter the name of your cluster's GCP principal you determined in step 3. 4. In the **Select a role** dropdown, select the role you created in step 4. 5. Click **SAVE**. 6. Use one of the following Cloud API commands to enable log export for your CockroachDB Advanced 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 Advanced cluster with **default** logging configuration, issue the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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": "{gcp_project_id}"}' ``` Where: * {'{cluster_id}'} is your CockroachDB Advanced cluster ID as determined in step 3. * {'{secret_key}'} is your CockroachDB Advanced 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 Advanced cluster. This name will appear in the name of each log written to GCP Cloud Logging. * {'{gcp_project_id}'} is your GCP project ID, as shown in your GCP Cloud Console [Settings page](https://console.cloud.google.com/iam-admin/settings). 2. To enable log export for your CockroachDB Advanced 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: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "type": "GCP_CLOUD_LOGGING", "log_name": "default", "auth_principal": "{gcp_project_id}", "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](#what-log-channels-are-supported) 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](https://jsonformatter.org/json-minify). The preceding configuration becomes the following single line: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} {"type":"GCP_CLOUD_LOGGING","log_name":"default","auth_principal":"{gcp_project_id}","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 Advanced cluster with the preceding configuration, issue the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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":"{gcp_project_id}","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 Advanced cluster ID as determined in step 2. * {'{secret_key}'} is your CockroachDB Advanced API key. Refer to API Access for instructions on generating this key. * {'{gcp_project_id}'} is your GCP project ID, as shown in your GCP Cloud Console [Settings page](https://console.cloud.google.com/iam-admin/settings). 7. 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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 across all nodes is complete, and logs will begin appearing in GCP Cloud Logging. Since the configuration is applied to cluster nodes in a rolling fashion, you may see some logs appear even before the `GET` command returns an `ENABLED` status. 8. Once log export has been enabled, you can access logs from your CockroachDB Advanced cluster directly in GCP Cloud Logging's [Log Explorer](https://console.cloud.google.com/logs/query). **This feature is in limited access** and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change. CockroachDB Advanced exports logs to Azure Monitor using the `AZURE_LOG_ANALYTICS_V2` log export type, which sends logs through the Azure Monitor [Logs Ingestion API](https://learn.microsoft.com/azure/azure-monitor/logs/logs-ingestion-api-overview) using a Data Collection Endpoint (DCE) and Data Collection Rule (DCR), and authenticates with a Microsoft Entra app registration. There are two parts to this integration: resource configuration in the Azure portal, and CockroachDB's automatic log export configuration. In the following steps, you will create these resources in the Azure portal: * A Log Analytics workspace * A Data Collection Endpoint * A Data Collection Rule * An app registration with a client secret * The required role assignments When you enable log export on a CockroachDB Cloud cluster, CockroachDB automatically creates the following: * The custom tables, one per log group * The DCR stream declarations and data flows for each log group You do not create tables or streams manually. ### Prerequisites Before you begin, ensure that you have the following: * An Azure subscription in which you can create resources and assign roles. Assigning roles requires the Owner or User Access Administrator role on the relevant scopes. * A CockroachDB Cloud API key for the Cloud organization. Refer to API Access for instructions on generating this key. ### Step 1. Create a Log Analytics workspace 1. Create a workspace by following Microsoft's [Create a Log Analytics workspace](https://learn.microsoft.com/azure/azure-monitor/logs/quick-create-workspace?tabs=azure-portal) instructions. 2. Open the workspace, select **JSON View**, and copy its **Resource ID**. This is the `azure_workspace_resource_id` value for the enable request, for example `/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.OperationalInsights/workspaces/{workspace_name}`. ### Step 2. Create a Data Collection Endpoint (DCE) 1. In Azure Monitor, select **Data Collection Endpoints**, then **Create**. Place the DCE in the same region as the workspace. 2. From the DCE **Overview**, copy the **Logs Ingestion** URI. This is the `azure_dce_endpoint` value for the enable request, for example `https://{dce_name}.{region}.ingest.monitor.azure.com`. 3. From the DCE **JSON View**, copy the DCE **Resource ID**. You reference it when you create the Data Collection Rule. ### Step 3. Create a Data Collection Rule (DCR) The DCR must exist before you enable log export, and it must already list the workspace as a Log Analytics destination. Create it from an ARM template: 1. In the Azure portal, search for **Deploy a custom template**, then select **Build your own template in the editor**. 2. Paste the following template, substituting your DCE resource ID, your workspace resource ID, and the Azure region used by the Log Analytics workspace and the DCE, such as `centralus`: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "resources": [ { "type": "Microsoft.Insights/dataCollectionRules", "apiVersion": "2024-03-11", "name": "crdb-logs-dcr", "location": "{region}", "properties": { "dataCollectionEndpointId": "{dce_resource_id}", "streamDeclarations": {}, "destinations": { "logAnalytics": [ { "workspaceResourceId": "{workspace_resource_id}", "name": "cockroachdb-workspace" } ] }, "dataFlows": [ { "streams": ["Microsoft-Syslog"], "destinations": ["cockroachdb-workspace"] } ] } } ] } ``` The `dataFlows` array cannot be empty, so the template includes a single `Microsoft-Syslog` flow as a placeholder. It has no data source and never emits anything, and CockroachDB adds its own data flows when you enable log export. The `name` under `destinations.logAnalytics` is an arbitrary label that only needs to match the value referenced in `dataFlows`. 3. Select **Save**, then **Review + create**, then **Create**. 4. After the deployment completes, open the DCR and copy the following values: * The **Immutable Id** from the DCR **Overview** (in the form `dcr-...`). This is the `azure_dcr_immutable_id` value. * The **Resource ID** from the DCR **JSON View**. This is the `azure_dcr_resource_id` value. The DCR may reside in a different resource group than the workspace. ### Step 4. Create an app registration 1. In Microsoft Entra, select **App registrations**, then **New registration**. Give it a name and register it. 2. From the app **Overview**, copy the **Directory (tenant) ID** (`azure_tenant_id`) and the **Application (client) ID** (`azure_client_id`). 3. Select **Certificates & secrets**, then **New client secret**. Copy the secret **Value** immediately, because it is shown only once. This is the `azure_client_secret` value. ### Step 5. Assign roles to the app registration The app registration needs the following role assignments. For each one, open the target resource, select **Access control (IAM)**, then **Add** > **Add role assignment**, select the role, and on the **Members** tab assign access to the app registration. The app registration does not appear in the member list until you search for it by name. | Target resource | Role | Purpose | | ------------------------ | ---------------------------- | -------------------------------------------------------------------------- | | Log Analytics workspace | Log Analytics Contributor | CockroachDB creates and updates the per-group custom tables. | | Data Collection Rule | Monitoring Contributor | CockroachDB updates the DCR to add streams and data flows. | | Data Collection Rule | Monitoring Metrics Publisher | CockroachDB ingests logs into the DCR at runtime. | | Data Collection Endpoint | Monitoring Contributor | Updating the DCR requires write access on the DCE that the DCR references. | After assigning the roles, allow time for the assignments to propagate before you enable log export. If enabling fails with a permission error immediately after you add the roles, wait and retry. ### Step 6. Enable log export Issue the following Cloud API command, substituting the values you captured in the previous steps. Each `log_name`, including the top-level value and each group's `log_name`, becomes an Azure custom table named with the value followed by `_CL`. Each value must start with a letter and contain only letters, digits, and underscores, and the resulting table name must be at most 45 characters. ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" \ --json '{ "type": "AZURE_LOG_ANALYTICS_V2", "log_name": "crdb_logs", "azure_tenant_id": "{azure_tenant_id}", "azure_client_id": "{azure_client_id}", "azure_client_secret": "{azure_client_secret}", "azure_dce_endpoint": "{azure_dce_endpoint}", "azure_dcr_immutable_id": "{azure_dcr_immutable_id}", "azure_workspace_resource_id": "{azure_workspace_resource_id}", "azure_dcr_resource_id": "{azure_dcr_resource_id}", "groups": [ { "log_name": "devops", "channels": ["OPS", "HEALTH"] }, { "log_name": "sqlaudit", "channels": ["SQL_EXEC", "SQL_PERF"] } ] }' ``` Replace `{cluster_id}` with your CockroachDB Advanced cluster ID, which is in the URL of the cluster's [Cloud Console](https://cockroachlabs.cloud/clusters) page, and `{secret_key}` with your API key. The `azure_*` values are the ones you captured in the previous steps. To view the other supported configuration options, such as redaction and omitted channels, consult the log export entry on the CockroachDB Cloud API Reference and select the **Schema** tab. Monitor the status of the configuration by issuing a `GET` request on the same endpoint until the status is `ENABLED`: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" ``` ### Step 7. Verify that logs are arriving 1. In the Azure portal, open your Log Analytics workspace, then select **Logs**. 2. Query the table for a log group, for example: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} crdb_logs_CL | sort by TimeGenerated desc | take 50 ``` 3. Confirm that recent rows appear. The first logs may not appear immediately after enabling, while the new DCR streams propagate through Azure. During that window, empty results or a brief stream-not-found condition are expected and resolve on their own. ### Troubleshooting * If enabling fails with a permission error, confirm all four role assignments described in the role assignment step, especially **Monitoring Contributor** on the Data Collection Endpoint, which is the most commonly missed. Recently added role assignments can also take time to propagate, so wait and retry. * If no logs appear after the propagation window, confirm the **Monitoring Metrics Publisher** role on the Data Collection Rule and that your query targets the correct table (the log name followed by `_CL`). Disabling log export stops log delivery and removes CockroachDB's stored credential for the sink. It does not delete the Azure resources you created or the tables, streams, and data flows that CockroachDB added. Re-enabling is idempotent. To fully remove the integration, delete the Azure resources yourself in the Azure portal. Log data already ingested into the tables is unaffected. **This feature is in limited access** and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change. Exporting logs to an OTLP/HTTP-compatible destination is available for CockroachDB Advanced clusters hosted on AWS, GCP, or Azure. This sink type is not available for CockroachDB Standard or Basic clusters. The `OTLP_HTTP` sink type exports logs to any destination that accepts the [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/) over HTTP, such as an observability platform or an OpenTelemetry Collector that you operate. Unlike the cloud-provider sink types, `OTLP_HTTP` does not use a cloud-provider IAM role or an `auth_principal`. It authenticates using the HTTP headers that you supply in `otlp_headers`. Perform the following steps to enable log export from your CockroachDB Advanced cluster to an OTLP/HTTP destination. 1. Find your CockroachDB Advanced cluster ID: 1. Visit the CockroachDB Cloud console [cluster page](https://cockroachlabs.cloud/clusters). 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`. 2. Determine the OTLP/HTTP endpoint and authentication headers for your destination: * The endpoint must use `https`. Provide either a base URL or the full logs URL ending in `/v1/logs`. CockroachDB appends `/v1/logs` to a base URL. The endpoint must not include embedded credentials, query parameters, or a fragment, and must not point at a private or internal address. * The authentication headers are the HTTP header name and value pairs that your destination requires, such as an `authorization` header carrying a bearer token or an `x-api-key` header. 3. To enable log export for your CockroachDB Advanced cluster, issue the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" \ --json '{ "type": "OTLP_HTTP", "log_name": "{log_name}", "otlp_endpoint": "{otlp_endpoint}", "otlp_headers": { "authorization": "{auth_header_value}" } }' ``` Where: * {'{cluster_id}'} is your CockroachDB Advanced cluster ID as determined in step 1. * {'{secret_key}'} is your CockroachDB Advanced 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 Advanced cluster. For the `OTLP_HTTP` sink type, this value is exported as the `cc.log_group` attribute on each log record, which you can use to filter among your log groups at the destination. * {'{otlp_endpoint}'} is the HTTPS endpoint of your OTLP/HTTP destination, as determined in step 2. * `otlp_headers` is a map of HTTP header names to values used to authenticate with your destination, as determined in step 2. Provide one entry per required header. To customize the configuration, for example to redact log entries, omit log channels, or route channels to separate log names, add the same options shown for the other sink types. Consult the log export entry on the CockroachDB Cloud API Reference and select the **Schema** tab for the supported options. The `enable_sending_queue` option is not supported for the `OTLP_HTTP` sink type. 4. 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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`, indicating that the configuration has been applied across all nodes. To confirm that logs are reaching the destination, check the `delivery_status` field described in [Monitor the status of a log export configuration](#monitor-the-status-of-a-log-export-configuration). This field may not appear immediately. The values in `otlp_headers` are stored securely and are never returned by the `GET` command or written to logs. The `GET` response includes only the configured header names, in `otlp_header_names`. To update an existing `OTLP_HTTP` configuration without changing its headers, omit `otlp_headers` or send an empty map, which preserves the stored values. Send a non-empty map to replace them. The stored headers are preserved only when the endpoint stays on the same origin. If you change `otlp_endpoint` to a different origin, you must provide `otlp_headers` again. If the new destination does not require authentication headers, disable the existing configuration before enabling the new destination. #### Example configurations for common destinations The following examples show the endpoint and authentication header for several destinations. The endpoint often depends on your account's region or site, so use the value from your destination's configuration. For any destination not shown here, refer to that destination's OTLP/HTTP documentation for its endpoint and required headers. Datadog authenticates with a Datadog API key in the `dd-api-key` header. The endpoint depends on your [Datadog site](https://docs.datadoghq.com/opentelemetry/setup/otlp_ingest/logs/). ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" \ --json '{ "type": "OTLP_HTTP", "log_name": "cockroachdb", "redact": true, "otlp_endpoint": "https://otlp.us5.datadoghq.com/v1/logs", "otlp_headers": { "dd-api-key": "{datadog_api_key}" } }' ``` New Relic authenticates with a New Relic license key (not a user API key) in the `api-key` header. The endpoint depends on your [New Relic region](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/). ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" \ --json '{ "type": "OTLP_HTTP", "log_name": "cockroachdb", "redact": true, "otlp_endpoint": "https://otlp.eu01.nr-data.net/v1/logs", "otlp_headers": { "api-key": "{new_relic_license_key}" } }' ``` Grafana Cloud uses HTTP Basic authentication, with your instance ID as the username and an access policy token (with the `logs:write` scope) as the password. Supply the Base64 encoding of `{instance_id}:{access_policy_token}` in the `Authorization` header. The endpoint, instance ID, and token are available from your Grafana Cloud stack's [OpenTelemetry configuration](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/). ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request POST \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" \ --json '{ "type": "OTLP_HTTP", "log_name": "cockroachdb", "redact": true, "otlp_endpoint": "https://otlp-gateway-prod-ap-south-1.grafana.net/otlp", "otlp_headers": { "Authorization": "Basic {base64_instance_id_and_token}" } }' ``` Once log export has been enabled, logs generated going forward are sent to the specified cloud sink. Logs are not back-filled to the specified cloud sink. ## Send logs over a private cloud connection You can send logs to Amazon CloudWatch from private egress endpoints on your CockroachDB Cloud clusters to ensure they are sent over private connections within the cloud service. To learn more, read the egress private endpoints documentation. ## Monitor the status of a log export configuration To check the status of an existing CockroachDB Advanced log export configuration, use the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request GET \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" ``` Where: * {'{cluster_id}'} is your CockroachDB Advanced cluster's cluster ID, which can be found in the URL of your [Cloud Console](https://cockroachlabs.cloud/clusters) for the specific cluster you wish to configure, resembling `f78b7feb-b6cf-4396-9d7f-494982d7d81e`. * {'{secret_key}'} is your CockroachDB Advanced API key. Refer to API Access for instructions on generating this key. For the `OTLP_HTTP` sink type, once the configuration is `ENABLED`, the `GET` response also reports the live delivery health of the export pipeline in a `delivery_status` field: `DELIVERY_HEALTHY` when the destination is receiving log records normally, and `DELIVERY_UNHEALTHY` when the destination is rejecting or failing to receive a substantial fraction of log records. When delivery is unhealthy, `delivery_status_message` provides additional detail. The status is cause-neutral by design: an unhealthy status may indicate invalid credentials, a wrong endpoint, or a transient outage at the destination. This field may not appear immediately after the configuration reaches `ENABLED`. ## Update an existing log export configuration To update an existing CockroachDB Advanced log export configuration, make any necessary changes to your cloud provider configuration (e.g., Amazon CloudWatch or GCP Cloud Logging), then issue the same `POST` Cloud API command as shown in the [Enable log export](#enable-log-export) instructions for your cloud provider with the desired updated configuration. Follow the [Monitor the status of a log export configuration](#monitor-the-status-of-a-log-export-configuration) instructions to ensure the update completes successfully. ## Buffer logs with a sending queue **This feature is in limited access** and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change. To protect against log loss when the log export process restarts or the log sink is temporarily unreachable, you can enable a disk-backed sending queue for one log export group per cluster. Logs for that group are buffered on disk until they are delivered, providing at-least-once delivery. The sending queue is available for log export to Amazon CloudWatch. To enable the sending queue, set `enable_sending_queue` to `true` in one group in the `groups` array of a custom logging configuration, then issue the `POST` command as described in [Enable log export](#enable-log-export) or [Update an existing log export configuration](#update-an-existing-log-export-configuration). For example, the following group buffers audit logs in the `SENSITIVE_ACCESS` channel: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "log_name": "audit", "channels": ["SENSITIVE_ACCESS"], "enable_sending_queue": true } ``` With the sending queue enabled for a group: * Delivery of buffered logs is retried with exponential backoff until it succeeds, with no time limit. * Buffered logs survive restarts of the log export process and temporary sink outages. * Log export does not block the cluster if the log sink is unavailable. Enable the sending queue for a group that carries critical log channels, such as `SENSITIVE_ACCESS` for audit logs, rather than for high-volume operational channels. ## Disable log export To disable an existing CockroachDB Advanced log export configuration, and stop sending logs to a cloud log sink, use the following Cloud API command: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} curl --request DELETE \ --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \ --header "Authorization: Bearer {secret_key}" ``` Where: * {'{cluster_id}'} is your CockroachDB Advanced cluster's cluster ID, which can be found in the URL of your [Cloud Console](https://cockroachlabs.cloud/clusters) for the specific cluster you wish to configure, resembling `f78b7feb-b6cf-4396-9d7f-494982d7d81e`. * {'{secret_key}'} is your CockroachDB Advanced API key. Refer to API Access for instructions on generating this key. ## Limitations * When exporting to a cloud-provider log sink, a CockroachDB Advanced cluster can export logs only to the log sink of its host cloud provider: clusters hosted on AWS can export only to Amazon CloudWatch, clusters hosted on GCP can export only to GCP Cloud Logging, and clusters hosted on Azure can export only to Azure Monitor. The `OTLP_HTTP` sink type is not restricted to the host cloud provider's log sink. * The log export feature does not guarantee 100% log delivery. A log export group with the [sending queue](#buffer-logs-with-a-sending-queue) enabled provides at-least-once delivery. Groups without the sending queue do not. ## CockroachDB Advanced log export Frequently Asked Questions (FAQ) Yes, use the `redact: true` log configuration option. Refer to Redact logs for more information. Yes, use the custom log configuration step for your cloud provider, and specify multiple `groups`, each with a unique `log_name` value, in your configuration. The cloud-provider log sinks are tied to your cluster's host cloud provider: a cluster on AWS can export to Amazon CloudWatch, a cluster on GCP can export to GCP Cloud Logging, and a cluster on Azure can export to Azure Monitor. To send logs to a destination that is not tied to your cluster's host cloud provider, use the `OTLP_HTTP` sink type, which exports to any OTLP/HTTP-compatible destination. No, logs for each region in your cluster are exported to the corresponding cloud log sink region configured for your account. For AWS, ensure that the target Amazon CloudWatch log group is configured with the same name in all target regions, and that the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles) you are using has permission to access each regional log group. For GCP, you can configure [Log Buckets](https://cloud.google.com/logging/docs/buckets) to collect logs from different regions, as well as assign individual retention policies by region if desired. By default, all logs written to GCP Cloud Logging are written to a `_Default` bucket, in the "global" region. You can export the following CockroachDB log channels: `SESSIONS`, `OPS`, `HEALTH`, `STORAGE`, `SQL_SCHEMA`, `USER_ADMIN`, `PRIVILEGES`, `SENSITIVE_ACCESS`, `SQL_EXEC`, `SQL_PERF`, and `CHANGEFEED`. Log channels, such as `DEV`, `KV_DISTRIBUTION`, `SQL_INTERNAL_PERF`, and `TELEMETRY`, cannot be exported from CockroachDB Advanced. These are for Cockroach Labs internal use cases and are not meant for external use. If you need access to additional logs, contact [Support](https://support.cockroachlabs.com/hc). Yes, the SQL Audit Log is exported via the `SENSITIVE_ACCESS` log channel by default, as long as you have previously enabled audit logging on desired tables using the `ALTER TABLE...EXPERIMENTAL_AUDIT` statement. No, the CockroachDB Advanced log export feature does not support use of an AWS External ID. You must configure a cross-account IAM Role as described in the [Enable log export](#enable-log-export) instructions. No, log export configuration uses the CockroachDB Cloud API syntax. For example, log export uses `min_level` to define log severity levels, while CockroachDB uses `filter`. Log messages received from CockroachDB Advanced nodes that are not yet fully started may arrive without a node number appended to the log name, in the format `{logname}.n`. Node-specific log messages, as they are received, are written to node-specific logs in the format `{logname}.n1`, `{logname}.n2`, etc., where the number following the `n` characters is the node ID. Refer to [Log Name Format](#log-name-format). ## Troubleshooting ### Amazon CloudWatch Most log export errors stem from incorrect AWS IAM configuration. Ensure you have followed steps 1 through 6 of the [Enable log export](#enable-log-export) instructions closely, and that you have a **cross-account** IAM role which trusts your CockroachDB Advanced AWS account ID (as determined in step 3) and has permission to write to your specified log group in CloudWatch (as created in step 1). When supplying the [Amazon Resource Name (ARN)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces) to step 8, be sure you are supplying the ARN for the `CockroachCloudLogExportRole` role, **not** the ARN for the `CockroachCloudLogExportPolicy` policy. Whether you are using the default logging configuration or the custom configuration: be sure to supply this ARN to the `auth_principal` parameter, in the `--data` payload. ### GCP Cloud Logging When supplying the GCP project ID in step 6a or 6b, be sure you use the **Project ID**, and not the **Project Name**. Both are shown on the Google Cloud Console [Settings page](https://console.cloud.google.com/iam-admin/settings). You do not need to create a GCP service account to enable or manage log export. The GCP principal mentioned in step 3 and used in step 5c is already created for you. These steps simply determine the account name of this principal, which is specific to your cluster.