To find out if this integration is available in your organization, see your Datadog Integrations page or ask your organization administrator.
To initiate an exception request to enable this integration for your organization, email support@ddog-gov.com.
Trajectory Overview dashboard with session activity and week-over-week trends
Overview
Trajectory is in Preview.
Trajectory helps you understand how AI coding agents such as Claude Code,
Codex, and Cursor are used. It captures sessions, tool calls, token usage, and
estimated costs so you can investigate problems and compare activity across
projects and teams. Explore sessions locally or send metrics and traces to
Datadog. Custom rules called Markers track behaviors such as retries or
particular commands.
This integration includes a dashboard for Trajectory deployment, data capture,
and delivery to Datadog.
Setup
Managed endpoint installation
To deploy Trajectory across company devices through MDM or UEM, follow the
Managed Endpoint Deployment guide.
Local installation
Run the installer from the Trajectory repository:
bash <(curl -fsSL https://raw.githubusercontent.com/datadog-labs/trajectory/main/install.sh)
Follow the interactive setup to configure your coding agents and Datadog
destination. Then run trajectory setup check and follow its suggested next
steps.
The Datadog integration installs automatically when Datadog receives
trajectory.session.count.
Uninstallation
Managed endpoints
Contact your endpoint-management administrator to remove Trajectory through
your organization’s MDM or UEM tooling. The administrator should first remove
the device’s Trajectory deployment assignment or policy so it is not
automatically reinstalled. See the Managed Endpoint Deployment guide for
the managed deployment model and endpoint verification commands.
Local installations
For a personal installation, run the Trajectory uninstaller:
bash <(curl -fsSL https://raw.githubusercontent.com/datadog-labs/trajectory/main/uninstall.sh)
The uninstaller removes the binary, helper assets, and managed coding-agent
integrations. It preserves your configuration and captured session data by
default. Add --dry-run to preview the changes or --help to see cleanup
options.
After stopping telemetry at its source, uninstall the integration tile in
Datadog. If a deployment continues to send trajectory.session.count, the
tile can be installed automatically again.
Data Collected
Metrics
| |
|---|
trajectory.instrumentation.capture.gap
(count) | Missing or inconsistent evidence between a client source and canonical capture. |
trajectory.instrumentation.capture.hook_event
(count) | Receipt-backed client hook admissions and duplicate retry outcomes. |
trajectory.instrumentation.capture.hook_latency_ms
(gauge) | Distribution of end-to-end server-side hook capture request latency.
Shown as millisecond |
trajectory.instrumentation.capture.write_latency_ms
(gauge) | Distribution of hook-to-JSONL and JSONL-to-ingest write latency by capture signal.
Shown as millisecond |
trajectory.instrumentation.derivation.correction
(count) | Telemetry derivation corrections produced by reconciliation or repair. |
trajectory.instrumentation.derivation.fallback
(count) | Telemetry values derived from a lower-fidelity fallback source. |
trajectory.instrumentation.health.emit_dropped
(count) | Instrumentation health records dropped by sanitization queue pressure or local write failure. |
trajectory.instrumentation.lifecycle.incident
(count) | Privacy-bounded capture update owner retirement and replacement lifecycle incidents. |
trajectory.instrumentation.publish.attempt
(count) | Publish attempts for spans metrics event logs and module outputs by outcome. |
trajectory.instrumentation.publish.failure
(count) | Telemetry publish failures including local validation rejections and destination delivery failures. |
trajectory.instrumentation.publish.latency_ms
(gauge) | Distribution of bounded publish latency by signal and destination class.
Shown as millisecond |
trajectory.instrumentation.runtime_reconcile.attempt
(count) | Autonomous runtime reconciliation attempts by trigger handoff mode and result. |
trajectory.ops.agent.active_sessions
(gauge) | Fresh active coding-agent sessions deduplicated across concurrent Trajectory serve processes. |
trajectory.ops.agent.present
(gauge) | Daily inventory state for each supported coding-agent client on a host. |
trajectory.ops.agent.version
(gauge) | Daily installed version inventory for each detected supported coding-agent client. |
trajectory.ops.binary.heartbeat
(gauge) | Fresh running Trajectory process count or 1 for the installed or desired binary state. |
trajectory.ops.convergence.heartbeat
(gauge) | Current Trajectory deployment convergence state for a host. |
trajectory.ops.install.auto_instrument_state
(gauge) | Observed managed auto-instrument readiness where 1 is ready and 0 is a proven capture gap. |
trajectory.ops.org_sync.success_age_seconds
(gauge) | Seconds since the last observed successful managed organization configuration sync or -1 when none has been observed.
Shown as second |
trajectory.ops.required_destination.health
(gauge) | Required destination health where 1 is active 0 is proven unhealthy and -1 is unknown or out of scope. |
trajectory.serve.capture.request_error_total
(count) | Capture HTTP requests that returned an error response or encountered a handler failure. |
trajectory.serve.goroutine.panic_recovered_total
(count) | Serve background goroutine panics recovered by restart or bounded give-up handling. |
trajectory.serve.local_state.publish_ledger_held_claims
(gauge) | Publish deduplication ledger claims held past any plausible live publish. |
trajectory.serve.terminal_recovery.oldest_age_seconds
(gauge) | Age of the oldest receipt-backed terminal projection still awaiting recovery.
Shown as second |
trajectory.serve.terminal_recovery.pending
(gauge) | Receipt-backed terminal projections awaiting complete finalization by feature. |
trajectory.session.count
(count) | Live coding-agent session starts excluding passive discovery and historical backfill. |
trajectory.turn.completed
(count) | Completed coding-agent turns. |
Service Checks
Trajectory does not include any service checks.
Events
Trajectory does not include any events.
Troubleshooting
The integration tile or its dashboard is not visible. This integration
installs itself only after Datadog receives the
trajectory.session.count metric. Verify that this metric is arriving in
the intended Datadog organization.
Dashboard widgets are empty. The dashboard groups by the version,
role, cohort, managed, and convergence_status tags. If a deployment
does not submit these tags, its data does not appear under the corresponding
template variable filters.
Support
Start with the out-of-the-box Trajectory dashboards in Datadog to check
deployment and telemetry health. For local investigation, open ~/.trajectory
in your coding agent and ask it to help inspect Trajectory’s configuration,
logs, and session data. Run trajectory doctor for diagnostics, and see the
user guide for more commands and troubleshooting.
Further Reading
Additional helpful documentation, links, and articles:
