AgentInstrumentation

Instrumentation Agent

Last updated on June 4, 2026

The Osuite Instrumentation Agent integrates with your AI IDE and instruments your code for you. It detects your language, framework, and key libraries, looks up the right OpenTelemetry packages, writes the SDK init module, and wires up traces and logs — so most services are live in Osuite in under an hour, not the weeks instrumentation usually takes.

This is the “before the incident” half of Osuite: get full visibility fast, with no proprietary agents and no hand-written OTel boilerplate.

Prerequisites

  • An Osuite Cloud account
  • Your Osuite API key

Step 1: Create your API key

An API key lets the agent and CLI interact with Osuite. Create one in the Osuite UI under Settings → API Keys.

Step 2: Install the Osuite CLI

npm install @osuite/cli -g && osuite init-ai

osuite init-ai installs the Osuite agent skills globally so your AI IDE can invoke them.

Step 3: Authenticate the CLI

Add the following to your shell profile:

export OSUITE_API_ENDPOINT=https://api.<region>.osuite.io
export OSUITE_API_KEY=<your api key>

Run osuite whoami to verify that you are authenticated.

Step 4: Instrument your code

Open your project in your AI IDE (Cursor, Antigravity, etc.) and trigger the agent:

/osuite-instrument instrument this service to send traces and logs to Osuite, including the database and Kafka clients

The agent detects your stack, presents a written plan (packages to install, files to create or modify, the environment variables you’ll need), and — once you approve — installs the packages, writes the init module, edits your entry point, and generates an instrumentation.md for your deployment. Your existing logger.info(...) calls keep working unchanged; the OTel logs bridge just exports a copy of each record with the active trace ID attached.

If you have a specific requirement, say so in the prompt and the agent will account for it.

Step 5: Set the required environment variables

The agent writes these into your project, but you must fill in the endpoint and token for your account:

OTEL_SERVICE_NAME="my-service"
OTEL_EXPORTER_OTLP_ENDPOINT="ingest.<region>.osuite.io:443"
OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your ingest token>"
OTEL_RESOURCE_ATTRIBUTES="service.environment=dev"

Note: service.environment is required by Osuite to group telemetry by environment (prod, staging, dev). Use this Osuite-specific key — not the standard deployment.environment.

Step 6: Start your application and verify

Start your application, generate some traffic, and open the Osuite UI. You should see traces under Traces, logs streaming under Logs, and metrics in Metrics → Metrics explorer.

Troubleshooting

If nothing appears after 60 seconds, check:

  • The required environment variables are all set
  • The ingest token is correct
  • The OTLP endpoint is reachable from where your service runs (not blocked by a firewall)
  • Your application is actually handling requests — some frameworks only emit spans when a request is served

Next steps

Previous
Osuite AI Agents
Next
Investigation Agent