--- 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.1.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) shows you how your developers use AI coding agents. It records each agent session, including tool calls, token usage, and estimated cost, so you can investigate problems and compare activity across projects and teams. You can explore sessions on your own machine or send metrics and traces to Datadog. Custom rules called *Markers* track specific behaviors, such as retries or particular commands. This integration includes a dashboard for monitoring Trajectory deployment, data capture, and delivery to Datadog. Its **MDM Health** tab shows whether setup worked, coding agents connected, and company settings sync on MDM-deployed devices. Its **Auto-Update Health** tab shows whether devices run their target Trajectory version and where updates are stuck. ### Supported coding agents{% #supported-coding-agents %} Trajectory supports the following coding agents: - Claude Code - Claude Desktop (macOS) - Codex CLI - Cursor Desktop - Gemini CLI - Antigravity CLI - OpenCode - Pi More than 25 other agents, including GitHub Copilot CLI, Windsurf, and Zed, are available in beta or preview. See [Supported Clients](https://github.com/datadog-labs/trajectory/blob/main/docs/SUPPORTED-CLIENTS.md) for the full list, supported versions, and setup details for each agent. ### Trajectory and Agent Console{% #trajectory-and-agent-console %} Trajectory captures what happens inside the coding agent: sessions, tool calls, repositories, developer interactions, and outcomes. [Agent Console](https://docs.datadoghq.com/ai_agents_console.md) combines this data with other integrations, giving you an organization-wide view of AI-assisted development. You don't need Agent Console to use Trajectory. Without it, you can still explore Trajectory data locally and in Datadog. ## Setup{% #setup %} Start with step 1 to try Trajectory on one machine. When you're ready to roll it out across your organization, continue to step 2. ### Prerequisites{% #prerequisites %} - macOS, Linux, or Windows. On Windows, run the installer from Git Bash, MSYS2, or Cygwin. - A Datadog API key and your [Datadog site](https://docs.datadoghq.com/getting_started/site.md), to send data to Datadog. To capture sessions locally without sending data, leave the API key prompt blank. You can set up Datadog export later with `trajectory destination configure`. ### Step 1: Try Trajectory on your machine{% #step-1-try-trajectory-on-your-machine %} 1. 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) ``` 1. Follow the interactive prompts. The installer detects the coding agents on your machine and asks where to send data in Datadog. 1. Run `trajectory setup check` and follow any suggested next steps. 1. Run `trajectory publish validate` to confirm that your Datadog configuration and credentials are valid. 1. Start a session in one of your coding agents, then run `trajectory status` to confirm that Trajectory captured it. After Datadog receives the `trajectory.session.count` metric, it installs the Trajectory integration tile and dashboard automatically. ### Step 2: Roll out Trajectory with MDM{% #step-2-roll-out-trajectory-with-mdm %} To deploy Trajectory to company devices with a mobile device management (MDM) or unified endpoint management (UEM) tool, follow the [Managed Endpoint Deployment guide](https://github.com/datadog-labs/trajectory/blob/main/docs/MANAGED-ENDPOINTS.md). The guide covers `trajectory-mdm`, an administrator helper that prepares a policy bundle for your MDM provider. The bundle specifies your organization's approved coding agents and telemetry tags. ## Uninstallation{% #uninstallation %} {% collapsible-section %} **Uninstall Trajectory from your machine** See [Uninstall](https://github.com/datadog-labs/trajectory/blob/main/docs/USER-GUIDE.md#uninstall) in the Trajectory user guide. {% /collapsible-section %} {% collapsible-section %} **Uninstall Trajectory from managed devices** Ask your endpoint management administrator to remove Trajectory through your organization's MDM or UEM tool. The administrator must first remove the device's Trajectory deployment assignment or policy. Otherwise, the tool reinstalls Trajectory automatically. See the [Managed Endpoint Deployment guide](https://github.com/datadog-labs/trajectory/blob/main/docs/MANAGED-ENDPOINTS.md) for the deployment model and verification commands. {% /collapsible-section %} {% collapsible-section %} **Remove the integration tile from Datadog** After you stop sending data from every device, uninstall the Trajectory integration tile in Datadog. If any device still sends `trajectory.session.count`, Datadog installs the tile again automatically. {% /collapsible-section %} ## Data Collected{% #data-collected %} ### Metrics{% #metrics %} Datadog installs this integration when it receives the following metric: - `trajectory.session.count`: live coding-agent session starts | | | | | **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.agent_state**(gauge) | Managed setup result for each coding-agent client on a host where 1 is the latest result and 0 is a result replaced by a later setup run. | | **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.install.current_state**(gauge) | Managed setup outcome for a host where 1 is the latest outcome and 0 is an outcome replaced by a later setup run. | | **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.ops.update.wait_age_seconds**(gauge) | Seconds a host has waited to install or activate its auto-update target release.*Shown as second* | | **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.** The 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's template variables filter by the `trajectory.user` and `trajectory.version` tags. If a deployment does not submit these tags, its data does not appear when those filters are set. Most **MDM Health** widgets only count MDM-deployed devices, and setup reports only when it runs, so use a time frame of at least a week. Devices that run Trajectory versions older than 0.6.0 don't report whether auto-update is enabled, so most **Auto-Update Health** counts leave them out. ## Support{% #support %} To check deployment and telemetry health, start with the out-of-the-box Trajectory dashboard in Datadog. To investigate locally, open `~/.trajectory` in your coding agent and ask it to help you 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)