curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--json '{"auth_principal":"my-gcp-project-id","groups":[{"channels":["OPS","HEALTH"],"log_name":"devops","min_level":"WARNING"}],"log_name":"default","omitted_channels":["SESSIONS","SQL_PERF"],"redact":true,"shared_key":"shared-key","type":"GCP_CLOUD_LOGGING"}'{
"cluster_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"delivery_status": "DELIVERY_HEALTHY",
"delivery_status_message": "<string>",
"spec": {
"auth_principal": "<string>",
"aws_external_id": "<string>",
"azure_client_id": "<string>",
"azure_client_secret": "<string>",
"azure_dce_endpoint": "<string>",
"azure_dcr_immutable_id": "<string>",
"azure_dcr_resource_id": "<string>",
"azure_shared_key": "<string>",
"azure_tenant_id": "<string>",
"azure_workspace_resource_id": "<string>",
"groups": [
{
"channels": [
"<string>"
],
"log_name": "<string>",
"enable_sending_queue": true,
"min_level": "UNSPECIFIED",
"redact": true
}
],
"log_name": "<string>",
"omitted_channels": [
"<string>"
],
"otlp_endpoint": "<string>",
"otlp_header_names": [
"<string>"
],
"redact": true,
"region": "<string>",
"type": "AWS_CLOUDWATCH"
},
"status": "DISABLED",
"updated_at": "2023-11-07T05:31:56Z",
"user_message": "<string>"
}{
"code": 123,
"details": [
{
"@type": "<string>"
}
],
"message": "<string>"
}Create or update the Log Export configuration for a cluster
Can be used by the following roles assigned at the organization, folder or cluster scope:
- ORG_ADMIN
- CLUSTER_ADMIN
- CLUSTER_OPERATOR_WRITER
curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/logexport \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--json '{"auth_principal":"my-gcp-project-id","groups":[{"channels":["OPS","HEALTH"],"log_name":"devops","min_level":"WARNING"}],"log_name":"default","omitted_channels":["SESSIONS","SQL_PERF"],"redact":true,"shared_key":"shared-key","type":"GCP_CLOUD_LOGGING"}'{
"cluster_id": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"delivery_status": "DELIVERY_HEALTHY",
"delivery_status_message": "<string>",
"spec": {
"auth_principal": "<string>",
"aws_external_id": "<string>",
"azure_client_id": "<string>",
"azure_client_secret": "<string>",
"azure_dce_endpoint": "<string>",
"azure_dcr_immutable_id": "<string>",
"azure_dcr_resource_id": "<string>",
"azure_shared_key": "<string>",
"azure_tenant_id": "<string>",
"azure_workspace_resource_id": "<string>",
"groups": [
{
"channels": [
"<string>"
],
"log_name": "<string>",
"enable_sending_queue": true,
"min_level": "UNSPECIFIED",
"redact": true
}
],
"log_name": "<string>",
"omitted_channels": [
"<string>"
],
"otlp_endpoint": "<string>",
"otlp_header_names": [
"<string>"
],
"redact": true,
"region": "<string>",
"type": "AWS_CLOUDWATCH"
},
"status": "DISABLED",
"updated_at": "2023-11-07T05:31:56Z",
"user_message": "<string>"
}{
"code": 123,
"details": [
{
"@type": "<string>"
}
],
"message": "<string>"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
log_name is an identifier for the logs in the customer's log sink. For AZURE_LOG_ANALYTICS_V2, it must start with a letter and contain only letters, digits, and underscores.
LogExportType identifies the destination used for exported logs. Cloud-native destinations use their provider's logging service, while OTLP_HTTP sends logs to a customer-configured OTLP/HTTP endpoint.
- AZURE_LOG_ANALYTICS: AZURE_LOG_ANALYTICS is the legacy Azure export path via the HTTP Data Collector API (retiring 2026-09-14). Deprecated: use AZURE_LOG_ANALYTICS_V2 instead.
- AZURE_LOG_ANALYTICS_V2: AZURE_LOG_ANALYTICS_V2 exports to Azure Monitor via the Logs Ingestion API and DCR-based ingestion, replacing the deprecated AZURE_LOG_ANALYTICS path that uses the HTTP Data Collector API (retiring 2026-09-14). V2 authenticates with a tenant/client/secret + DCR endpoint and rule, whereas the legacy type uses a workspace ID + shared key.
AWS_CLOUDWATCH, GCP_CLOUD_LOGGING, AZURE_LOG_ANALYTICS, AZURE_LOG_ANALYTICS_V2, OTLP_HTTP auth_principal is used in different contexts based on integration. CloudWatch: AWS Role ARN that identifies a role that the cluster account can assume to write to CloudWatch GCP Cloud Logging: GCP Project ID that the cluster service account has permissions to write to for cloud logging. Azure Log Analytics (AZURE_LOG_ANALYTICS): CustomerID or WorkspaceID. Required for AWS_CLOUDWATCH, GCP_CLOUD_LOGGING, and AZURE_LOG_ANALYTICS. Not used for AZURE_LOG_ANALYTICS_V2 or OTLP_HTTP. OTLP_HTTP authenticates via otlp_headers (see otlp_endpoint / otlp_headers).
aws_external_id to include when assuming the IAM role specified by role_arn. Optional. A specific value may be required by the role's trust policy. Only supported for Advanced clusters on AWS. If provided for a Standard cluster, the request is rejected.
Azure client ID for the app registration used by the Logs Ingestion API. Required when type is AZURE_LOG_ANALYTICS_V2.
Azure client secret for the app registration used by the Logs Ingestion API. Required when type is AZURE_LOG_ANALYTICS_V2.
Logs ingestion endpoint of the Azure Data Collection Endpoint (DCE). For example, https://{dce-name}.{region}.ingest.monitor.azure.com. Required when type is AZURE_LOG_ANALYTICS_V2.
Immutable ID of the Azure Data Collection Rule (DCR), for example dcr-... Required when type is AZURE_LOG_ANALYTICS_V2.
Full ARM resource ID of the Azure Data Collection Rule (DCR). Cockroach Cloud reads and updates this DCR to add streams for each configured log group. For example, /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Insights/dataCollectionRules/{dcr-name}. Required when type is AZURE_LOG_ANALYTICS_V2.
The primary or the secondary connected sources client authentication key. This is used to export logs to Azure Log Analytics via the legacy HTTP Data Collector API. Deprecated: use azure_client_secret instead.
Azure tenant ID for the app registration used by the Logs Ingestion API. Required when type is AZURE_LOG_ANALYTICS_V2.
Full ARM resource ID of the Log Analytics workspace. Cockroach Cloud creates or updates the required custom tables for each configured log group. For example, /subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.OperationalInsights/workspaces/{workspace-name}. Required when type is AZURE_LOG_ANALYTICS_V2.
groups is a collection of log group configurations that allows the customer to define collections of CRDB log channels that are aggregated separately at the target sink.
Show child attributes
Show child attributes
omitted_channels is a list of channels that the user does not want to export logs for.
otlp_endpoint is the OTLP/HTTP URL for the OTLP_HTTP sink type. Customers may provide either a base endpoint or a full /v1/logs endpoint. Required when type is OTLP_HTTP.
otlp_headers are auth headers (name->value) for the OTLP_HTTP sink, e.g. {"authorization": "Bearer ..."}. Write-only: values are stored securely and never returned. For existing OTLP_HTTP configurations, omitting this field or sending an empty map preserves the stored headers; sending a non-empty map replaces them.
Show child attributes
Show child attributes
redact allows the customer to set a default redaction policy for
logs before they are exported to the target sink. If a group config
omits a redact flag and this one is set to true, then that group
will receive redacted logs.
region allows the customer to override the destination region for all logs for a cluster.
Response
A successful response.
LogExportClusterInfo contains a package of information that fully describes both the intended state of the log export configuration for a specific cluster but also some metadata around its deployment status, any error messages, and some timestamps.
LogExportDeliveryStatus reports whether logs are reaching the customer's destination. This is independent of LogExportStatus, which reports whether the integration is configured and running. Delivery health is currently reported only for OTLP_HTTP sinks.
- DELIVERY_HEALTHY: The destination is receiving log records normally.
- DELIVERY_UNHEALTHY: The destination is rejecting or failing to receive a substantial fraction of log records. The cause is intentionally not distinguished — it may be invalid credentials, a wrong endpoint, or a transient outage.
DELIVERY_HEALTHY, DELIVERY_UNHEALTHY Descriptive error message when delivery_status is DELIVERY_UNHEALTHY. Only populated for OTLP_HTTP sinks.
LogExportClusterSpecification contains all the data necessary to configure log export for an individual cluster. Users would supply this data via the API and also receive it back when inspecting the state of their log export configuration.
Show child attributes
Show child attributes
LogExportStatus encodes the possible states that a configuration can be in as it is created, deployed, and disabled.
DISABLED, DISABLING, DISABLE_FAILED, ENABLED, ENABLING, ENABLE_FAILED, CREDENTIALS_ERROR