Update to CockroachDB

{
  "description": "Configures log and metric export for CockroachDB Cloud clusters to external monitoring services including AWS CloudWatch, GCP Cloud Logging, and Datadog. Use when setting up log export for audit compliance, configuring metric export for monitoring, or troubleshooting log delivery issues.",
  "included_files": [
    {
      "relative_path": "references/cloud-provider-setup.md",
      "size_in_bytes": 5975
    }
  ],
  "name": "configuring-log-export",
  "skill_md_contents": "---\nname: configuring-log-export\ndescription: Configures log and metric export for CockroachDB Cloud clusters to external monitoring services including AWS CloudWatch, GCP Cloud Logging, and Datadog. Use when setting up log export for audit compliance, configuring metric export for monitoring, or troubleshooting log delivery issues.\ncompatibility: Requires CockroachDB Cloud Advanced plan. Requires ccloud CLI with Cluster Admin role and cloud provider IAM configuration.\n---\n\n# Configuring Log Export\n\nConfigures log and metric export for CockroachDB Cloud clusters to deliver cluster logs, audit logs, and performance metrics to external monitoring services. Supports AWS CloudWatch, GCP Cloud Logging, and third-party integrations like Datadog.\n\n## When to Use This Skill\n\n- Setting up log export to AWS CloudWatch or GCP Cloud Logging\n- Configuring metric export to CloudWatch or Datadog\n- Verifying that SQL audit logs are being exported to an external sink\n- Troubleshooting log export errors or missing logs\n- Estimating CloudWatch or logging service costs for CockroachDB log volume\n- Configuring log export via Terraform\n\n## Prerequisites\n\n- **CockroachDB Cloud Advanced plan** — Log export is not available on Basic or Standard plans\n- **ccloud CLI** authenticated with Cluster Admin role\n- **Cloud provider setup:**\n  - **AWS:** CloudWatch Logs group created, IAM role granting CockroachDB Cloud cross-account access\n  - **GCP:** Cloud Logging API enabled, service account with Logs Writer role\n- **Cluster ID:** Available from `ccloud cluster list`\n\n**Verify access:**\n```bash\nccloud auth whoami\nccloud cluster info <cluster-name> -o json\n# Look for \"plan\": \"ADVANCED\"\n```\n\n## Configuration Decisions\n\nBefore proceeding, determine which export destinations apply to the user's environment. Ask which options are relevant, then follow only the corresponding sections below.\n\n**Decision 1 — Log export destination:**\n- **AWS CloudWatch:** Use when the cluster runs on AWS and logs should go to CloudWatch Logs. Requires IAM cross-account role setup.\n- **GCP Cloud Logging:** Use when the cluster runs on GCP. Requires a service account with Logs Writer role.\n\n**Decision 2 — Metric export destination:**\n- **CloudWatch:** Use when metrics should go to AWS CloudWatch. Requires IAM role with `cloudwatch:PutMetricData` permission.\n- **Datadog:** Use when metrics should go to Datadog. Requires a Datadog API key and site.\n- **Skip:** No metric export needed at this time.\n\n## Steps\n\n### 1. Check Current Log Export Configuration\n\n```bash\n# Check if log export is currently configured\nccloud cluster info <cluster-name> -o json\n# Look for \"log_export_config\" in the output\n```\n\n### 2. Set Up Log Export to AWS CloudWatch\n\n> Follow this section only if the user selected **AWS CloudWatch** in Decision 1. Skip to Step 3 if using GCP Cloud Logging.\n\n#### 2.1 Create a CloudWatch Log Group\n\n```bash\n# Create a log group in AWS (if it doesn't exist)\naws logs create-log-group \\\n  --log-group-name cockroachdb-<cluster-name> \\\n  --region <aws-region>\n\n# Set retention policy (recommended)\naws logs put-retention-policy \\\n  --log-group-name cockroachdb-<cluster-name> \\\n  --retention-in-days 90 \\\n  --region <aws-region>\n```\n\n#### 2.2 Create an IAM Role for CockroachDB Cloud\n\nSee [cloud provider setup reference](references/cloud-provider-setup.md) for the complete IAM role policy.\n\nThe IAM role must:\n- Trust the CockroachDB Cloud AWS account as an allowed principal\n- Grant `logs:CreateLogStream`, `logs:PutLogEvents`, `logs:DescribeLogGroups`, `logs:DescribeLogStreams` permissions\n- Be scoped to the specific log group\n\n#### 2.3 Enable Log Export\n\n```bash\n# Enable log export to CloudWatch\nccloud cluster log-export create <cluster-id> \\\n  --log-group-name cockroachdb-<cluster-name> \\\n  --auth-principal <iam-role-arn> \\\n  --type AWS_CLOUDWATCH \\\n  --region <aws-region>\n```\n\n### 3. Set Up Log Export to GCP Cloud Logging\n\n> Follow this section only if the user selected **GCP Cloud Logging** in Decision 1. Skip if using AWS CloudWatch.\n\n#### 3.1 Enable Cloud Logging API\n\n```bash\ngcloud services enable logging.googleapis.com\n```\n\n#### 3.2 Grant CockroachDB Cloud Service Account Access\n\n```bash\n# Get the CockroachDB Cloud service account from ccloud cluster info\n# Grant Logs Writer role\ngcloud projects add-iam-policy-binding <gcp-project-id> \\\n  --member=\"serviceAccount:<cockroachdb-service-account>\" \\\n  --role=\"roles/logging.logWriter\"\n```\n\n#### 3.3 Enable Log Export\n\n```bash\nccloud cluster log-export create <cluster-id> \\\n  --auth-principal <gcp-project-id> \\\n  --type GCP_CLOUD_LOGGING\n```\n\n### 4. Configure Metric Export\n\n> Skip this section if the user selected **Skip** in Decision 2. Follow only the relevant subsection (4.1 or 4.2) based on the selected metric export destination.\n\nMetric export sends CockroachDB performance metrics to CloudWatch or Datadog.\n\n#### 4.1 Metric Export to CloudWatch\n\n```bash\nccloud cluster metric-export create cloudwatch <cluster-id> \\\n  --role-arn <iam-role-arn> \\\n  --target-region <aws-region>\n```\n\nThe IAM role for metric export needs `cloudwatch:PutMetricData` permission.\n\n#### 4.2 Metric Export to Datadog\n\n```bash\nccloud cluster metric-export create datadog <cluster-id> \\\n  --api-key <datadog-api-key> \\\n  --site <datadog-site>\n```\n\n**Datadog site values:** `datadoghq.com` (US), `datadoghq.eu` (EU), `us3.datadoghq.com` (US3), `us5.datadoghq.com` (US5)\n\n### 5. Verify Log and Metric Export\n\n```bash\n# Check log export status\nccloud cluster log-export list <cluster-id> -o json\n# Status should be ENABLED\n\n# Check metric export status\nccloud cluster metric-export list <cluster-id> -o json\n```\n\n**Verify log delivery in CloudWatch:**\n```bash\n# Check for recent log streams\naws logs describe-log-streams \\\n  --log-group-name cockroachdb-<cluster-name> \\\n  --order-by LastEventTime \\\n  --descending \\\n  --limit 5 \\\n  --region <aws-region>\n\n# Tail recent log events\naws logs tail cockroachdb-<cluster-name> \\\n  --since 1h \\\n  --region <aws-region>\n```\n\n**Verify audit logs are being exported:**\n\nAudit logs are included in the log export if SQL audit logging is enabled on the cluster. To confirm:\n\n```sql\n-- Check audit logging is enabled\nSHOW CLUSTER SETTING sql.log.admin_audit.enabled;\nSHOW CLUSTER SETTING sql.log.user_audit;\n```\n\nIf audit logging is enabled but audit events are not appearing in CloudWatch, check:\n1. Log export status is ENABLED\n2. The IAM role has correct permissions\n3. Log group name matches the configured export target\n4. Allow 5-10 minutes for initial log delivery\n\n### 6. Configure Log Export via Terraform\n\n```hcl\nresource \"cockroach_log_export_config\" \"main\" {\n  id         = cockroach_cluster.main.id\n  auth_principal = \"<iam-role-arn>\"\n  log_name       = \"cockroachdb-${cockroach_cluster.main.name}\"\n  type           = \"AWS_CLOUDWATCH\"\n  region         = \"<aws-region>\"\n}\n\nresource \"cockroach_metric_export_cloudwatch_config\" \"main\" {\n  id         = cockroach_cluster.main.id\n  role_arn       = \"<iam-role-arn>\"\n  target_region  = \"<aws-region>\"\n}\n```\n\n**Known Terraform issue:** Creating a cluster with log export and CMEK in the same `terraform apply` can cause a race condition. Apply the cluster first, then add log export and CMEK configurations in a subsequent apply.\n\n## Safety Considerations\n\n| Impact Type | Severity | Recommendation |\n|-------------|----------|----------------|\n| Log export enabling | Low | No impact on cluster operation |\n| Log export disabling | Low | Stops log delivery but does not affect cluster |\n| IAM misconfiguration | Medium | Log export will fail silently; monitor for delivery gaps |\n| Cost impact | Medium | High-volume clusters can generate significant CloudWatch/logging costs |\n| Terraform race condition | Medium | Apply cluster creation before log/CMEK config |\n\n**Cost planning:**\n- CockroachDB Cloud can generate 1-10 GB of logs per day per node depending on query volume and audit settings\n- CloudWatch Logs pricing: ~$0.50/GB ingestion + $0.03/GB storage/month (varies by region)\n- Enable log retention policies to control storage costs\n- Audit logging significantly increases log volume — plan accordingly\n\n**Do not:**\n- Delete the CloudWatch log group while log export is active (will cause delivery errors)\n- Revoke IAM permissions without disabling log export first\n- Enable cluster-wide SQL audit logging without considering the log volume increase\n\n## Rollback\n\n```bash\n# Disable log export\nccloud cluster log-export delete <cluster-id>\n\n# Disable metric export\nccloud cluster metric-export delete cloudwatch <cluster-id>\nccloud cluster metric-export delete datadog <cluster-id>\n```\n\nLog export can be re-enabled at any time with the same or different configuration. Historical logs are not re-sent — only new logs are exported after re-enabling.\n\n## References\n\n**Skill references:**\n- [Cloud provider IAM setup](references/cloud-provider-setup.md)\n\n**Related skills:**\n- [configuring-audit-logging](../configuring-audit-logging/SKILL.md) — Enable SQL audit logging (must be enabled for audit logs to appear in export)\n- [auditing-cloud-cluster-security](../audit-cloud-security/SKILL.md) — Run a full security posture audit\n\n**Official CockroachDB Documentation:**\n- [Export Logs From a CockroachDB Cloud Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/export-logs.html)\n- [Export Metrics From a CockroachDB Cloud Cluster](https://www.cockroachlabs.com/docs/cockroachcloud/export-metrics.html)\n- [Cloud API — Log Export](https://www.cockroachlabs.com/docs/cockroachcloud/cloud-api.html)\n"
}