Send Agent Relay logs to a SIEM

This page is for teams that ingest Agent Relay logs into a security information and event management (SIEM) system or another log platform that reads JSON lines. Agent Relay doesn't emit a separate event ID, so build searches and alerts on msg, level, logger_names, and values inside fields.

Set logFormat: json and ship the container's stderr to your SIEM with your usual log collector, as you would for Coder service logs.

Log levelsCopy Anchor Link

Each logLevel setting includes every more severe level:

Use info for SIEM ingestion. debug adds routine retries, poll backpressure, and license checks without adding alerting value. For Claude Code, debug also writes work order payload records that contain the decoded work order, including emails and repository URLs.

Record shapeCopy Anchor Link

Each JSON record has these top-level keys:

The reaper deletes finished and failed workspaces for both providers. Its records carry workspace_id and workspace_name, but no provider, pool, or session ID.

Provider-specific fieldsCopy Anchor Link

Both providers log the correlation fields. Each provider also logs identity fields and aliases that use its own API's names. An alias always carries the same value as the field it mirrors.

Because user_id means different things for each provider, use owner_id for the Coder user in reports that cover both.

Startup records also echo pool configuration, such as organization, organization_id, and template. Claude Code adds claude_tag_channel_user, and Cursor adds cursor_pool, relist_interval, and relist_jitter.

Failure and rebuild fieldsCopy Anchor Link

Claude Code nack records don't repeat the failure reason. Find it in the error or reason field of the WARN record written just before the nack.

Example recordsCopy Anchor Link

A Claude Code workspace build starting:

{
  "ts": "2026-10-14T16:02:11.912540118Z",
  "level": "INFO",
  "msg": "workspace build created",
  "caller": "/src/internal/workspacedispatcher/dispatcher.go:344",
  "func": "github.com/coder/agent-relay/internal/workspacedispatcher.(*Dispatcher).createWorkspace",
  "logger_names": ["claude-code-runners"],
  "fields": {
    "provider": "claude_code",
    "pool": "prod",
    "session_id": "00000000-1111-4222-8333-444444444444",
    "session_uuid": "00000000-1111-4222-8333-444444444444",
    "delivery_id": "77777777-6666-4555-8444-333333333333",
    "jti": "77777777-6666-4555-8444-333333333333",
    "attempt": "0",
    "client_platform": "web_claude_ai",
    "spawn_reason": "session_created",
    "account_id": "user_01AAAAAAAAAAAAAAAAAAAAAAAA",
    "account_email": "[email protected]",
    "agent_id": "",
    "org_service_name": "",
    "owner": "jdoe",
    "owner_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "username": "jdoe",
    "user_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "workspace_id": "99999999-8888-4777-8666-555555555555",
    "workspace_name": "cc-00000000-1111-4222-8333-44444"
  }
}

A Cursor claim that failed after a build error. The user sees message in Cursor:

{
  "ts": "2026-10-14T16:04:37.391402118Z",
  "level": "WARN",
  "msg": "failed the claim upstream, the user sees the message",
  "caller": "/src/internal/services/servicecursorworkers/fail.go:68",
  "func": "github.com/coder/agent-relay/internal/services/servicecursorworkers.(*Service).failClaim",
  "logger_names": ["cursor-workers"],
  "fields": {
    "provider": "cursor",
    "pool": "prod",
    "session_id": "bc-00000000-1111-4222-8333-444444444444",
    "request_id": "bc-00000000-1111-4222-8333-444444444444",
    "provider_user_id": 4242,
    "user_id": 4242,
    "delivery_id": "cw_77777777-6666-4555-8444-333333333333",
    "worker_id": "cw_77777777-6666-4555-8444-333333333333",
    "owner": "jdoe",
    "owner_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "stage": "building",
    "retryable": true,
    "message": "agent-relay: workspace build failed. Try again in a few minutes.",
    "detail": "workspace cur-bc-00000000-1111-4222-8333-4 job failed: terraform apply: exit status 1"
  }
}

ID prefixes show where a value comes from:

Parse recordsCopy Anchor Link

• Ingest stderr as one JSON object per line. Route lines that aren't JSON to a fallback index instead of dropping them, because a plain agent-relay: ... startup failure might be the only sign that the service never started.
• Use ts as the event time, not the ingestion time.
• Flatten fields, and map IDs and UUIDs as keyword or string types.
• Set field types explicitly:
  • Claude Code attempt is a string, not a number.
  • Cursor provider_user_id and user_id are numbers.
  • retryable is a boolean, and expected_spawn_seconds is a number.
  • deadline is an RFC 3339 timestamp.
  • Durations such as interval, retry_interval, relist_interval, and age are Go duration strings, such as 5s or 5m0s.
• Treat empty strings as missing. On Claude Code records, account_id, account_email, agent_id, and org_service_name are present but empty when they don't apply.
• Allow duplicate keys. Records written after Agent Relay creates a workspace can contain owner twice, and Claude Code nack records can contain attempt twice. Correlate users on owner_id, not owner.

Scope records to a providerCopy Anchor Link

• Select a provider's records by logger_names: claude-code-runners or cursor-workers. Some records carry no provider field, such as no claude code runner pools configured, claude provider disabled, so a filter on fields.provider alone misses them.
• Also collect reaper records, and attribute them by workspace_name prefix: cc- for Claude Code and cur- for Cursor. Join them to a session on workspace_id.
• Add fields.pool to the filter when one Agent Relay deployment serves more than one pool.

To measure user impact, count distinct session IDs, not records: session_uuid for Claude Code and session_id for Cursor. A retried session gets a new delivery_id under the same session ID, so one session can fail more than once.

Match rulesCopy Anchor Link

• Match on msg and level. Do not match on caller or func, because file paths, line numbers, and function names change between builds.
• msg text can change between Agent Relay releases. Recheck saved searches and alert rules after each upgrade.
• Alert on specific msg values, not on every WARN record. Several WARN messages describe automatic recovery, such as poll failed, retrying next interval, identity resolution failed, nacking retryable, and claim failed, retrying next pass.

Log-based alertsCopy Anchor Link

These alerts complement the suggested Prometheus alerts. Some conditions, such as a stranded Cursor claim, appear only in logs.

Retention and privacyCopy Anchor Link

• Keep logs for as long as your audit requirements need. Agent Relay doesn't keep session history, so your log platform is the record of who ran which session and why it failed.
• Use Prometheus metrics for rates and latency, and the SIEM for ordered event history, investigations, and the alerts above.
• Records can contain Coder usernames and user IDs, Anthropic account IDs, and Cursor user IDs. Claude Code records carry account_email on every record after work order verification, and Cursor refusal records carry user_email.
• Emails also appear inside error, detail, and job_error strings, such as identity warnings. Mask these fields, or restrict them with role-based access, along with the other user-identifying fields.

Learn moreCopy Anchor Link

• Monitor Agent Relay
• Troubleshoot Agent Relay
• Agent Relay configuration reference