# CloudWatch Log Integration (OpenTelemetry)

This integration ships broker logs from your CloudAMQP cluster to AWS CloudWatch Logs. It uses the **OpenTelemetry Protocol (OTLP)** over HTTP with AWS SigV4 authentication, and IAM role assumption. No access keys need to be shared.

## Prerequisites

This integration cannot create CloudWatch log groups or log streams. The log group and log stream must already exist in your AWS account before logs can be shipped. The CloudAMQP console pre-fills default names, but you must create matching resources in the [AWS CloudWatch console](https://console.aws.amazon.com/cloudwatch/) under **CloudWatch → Logs → Log groups:**

- Create a log group named `CloudAMQP` if you want to use the default value shown in the integration form, or create a log group with your own name. Here you can also specify retention and tags for the log group.
- Inside the log group, create a log stream named after your CloudAMQP cluster if you want to use the default value shown in the integration form, or create a log stream with your own name. All nodes in your cluster will ship logs to the same log stream. Each node can be identified by the attribute `resource.attributes.host.name`

## Authentication

This integration uses IAM role assumption. CloudAMQP assumes a role in your account using our service user and the External ID you provide. You only need to share the role ARN with CloudAMQP.

### Step 1 Create the IAM role

In the [AWS IAM console,](https://console.aws.amazon.com/iam/) create a new role. When asked for the trusted entity type, choose **Custom trust policy** (you will fill this in Step 2).

Attach the following permission policy to the role. Replace `YOUR_ACCOUNT_ID` with your AWS account ID and `YOUR_LOG_GROUP` with the name of the log group you created (default: `CloudAMQP`):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "logs:PutLogEvents",
      "Resource": "arn:aws:logs:*:YOUR_ACCOUNT_ID:log-group:YOUR_LOG_GROUP:log-stream:*"
    }
  ]
}
```

The `logs:PutLogEvents` permission allows CloudAMQP to publish log events to existing CloudWatch Logs streams.

### Step 2 Set the trust relationship

Set the role's trust policy to allow CloudAMQP to assume it. Replace `YOUR_EXTERNAL_ID` with the External ID shown in the integration form in the CloudAMQP console (or omit the `Condition` block entirely if you choose not to use an External ID):

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::714915985929:user/cloudamqp-metrics-publisher"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "YOUR_EXTERNAL_ID"
        }
      }
    }
  ]
}
```

The principal `arn:aws:iam::714915985929:user/cloudamqp-metrics-publisher` is the real CloudAMQP service user ARN, copy it as-is.

## Setting up in the CloudAMQP console

Open the CloudAMQP console, go to **Integrations → Add log integration → CloudWatch V2,** and fill in the following fields:

- **Role ARN**

  The ARN of the role you created in Step 1, e.g. `arn:aws:iam::YOUR_ACCOUNT_ID:role/YOUR_ROLE_NAME`

- **External ID**

  Optional. Use the auto-generated value or enter your own, it must match the value set in the trust policy.

- **Region**

  The AWS region where your log group is located, e.g. `us-east-1`

- **Log group**

  The name of an existing CloudWatch Logs log group. Defaults to `CloudAMQP` in the CloudAMQP console. If you keep this default, create a log group named `CloudAMQP` in AWS before saving the integration.

- **Log stream**

  The name of an existing log stream within the log group. Defaults to your CloudAMQP cluster name in the CloudAMQP console. If you keep this default, create a log stream with the same name as your cluster before saving the integration.

Click **Save** to activate the integration. Logs will begin shipping within a few minutes.

## Log record format

Each log record arrives in CloudWatch as a structured JSON object in the OpenTelemetry log data model. Here is an example record from a RabbitMQ node:

```json
{
  "resource": {
    "attributes": {
      "service.name": "my-cluster-name",
      "host.name": "my-cluster-name-01"
    }
  },
  "scope": {},
  "timeUnixNano": 1749999999483021000,
  "observedTimeUnixNano": 1749999999864126106,
  "severityNumber": 9,
  "severityText": "INFO",
  "body": "accepting AMQP connection 18.216.156.227:13208 -> 10.56.72.78:5672\n",
  "attributes": {
    "appname": "rabbitmq"
  },
  "traceId": "",
  "spanId": ""
}
```

Notable fields:

- `resource.attributes.service.name` — your CloudAMQP cluster name
- `resource.attributes.host.name` — the individual node hostname, useful for filtering on multi-node clusters
- `severityNumber` — mapped from the journald `PRIORITY` field following the [OpenTelemetry severity spec](https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber) (e.g. DEBUG = 5, INFO = 9, WARN = 13, ERROR = 17, FATAL = 21)
- `attributes.appname` — always `rabbitmq` or `lavinmq`

[← Back to Log Integrations](/docs/cloudamqp-integrations/#otel-logs)
