---
title: Trajectory
description: Monitor Trajectory instrumentation deployment and convergence.
breadcrumbs: Docs > Integrations > Trajectory
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Trajectory
Integration version1.0.0
{% callout %}
# Important note for users on the following Datadog sites: us2.ddog-gov.com

{% alert level="info" %}
To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator.

To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com).
{% /alert %}

{% /callout %}
Trajectory Overview dashboard with session activity and week-over-week trends
## Overview{% #overview %}

{% alert level="info" %}
Trajectory is in Preview.
{% /alert %}

[Trajectory](https://github.com/datadog-labs/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{% #setup %}

### Managed endpoint installation{% #managed-endpoint-installation %}

To deploy Trajectory across company devices through MDM or UEM, follow the [Managed Endpoint Deployment guide](https://github.com/datadog-labs/trajectory/blob/main/docs/MANAGED-ENDPOINTS.md).

### Local installation{% #local-installation %}

Run the installer from the [Trajectory repository](https://github.com/datadog-labs/trajectory):

```bash
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{% #uninstallation %}

### Managed endpoints{% #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](https://github.com/datadog-labs/trajectory/blob/main/docs/MANAGED-ENDPOINTS.md) for the managed deployment model and endpoint verification commands.

### Local installations{% #local-installations %}

For a personal installation, run the [Trajectory uninstaller](https://github.com/datadog-labs/trajectory/blob/main/uninstall.sh):

```bash
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{% #data-collected %}

### Metrics{% #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{% #service-checks %}

Trajectory does not include any service checks.

### Events{% #events %}

Trajectory does not include any events.

## Troubleshooting{% #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{% #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](https://github.com/datadog-labs/trajectory/blob/main/docs/USER-GUIDE.md) for more commands and troubleshooting.

## Further Reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [GitHub - datadog-labs/trajectory](https://github.com/datadog-labs/trajectory)
- [trajectory/docs/USER-GUIDE.md at main · datadog-labs/trajectory](https://github.com/datadog-labs/trajectory/blob/main/docs/USER-GUIDE.md)