Skip to content
Osuite Osuite Docs

Instrumentation Agent

The Osuite Instrumentation Agent works inside your existing coding tool. It detects the real language, framework, entry point, logging libraries, and existing OpenTelemetry setup before changing one selected service.

It supports any language with usable OpenTelemetry support. When the suitable integration is experimental, the agent may use it and will call that out in its result and production instructions.

Agent-led onboarding

Section titled “Agent-led onboarding”

Follow the agent setup to install the CLI and bundled skills. Then ask your coding agent to complete Osuite onboarding for the repository, including local verification.

The agent will:

  1. Run osuite setup and ask you to approve the browser connection.
  2. Select one service from the current repository context, asking only when the choice is ambiguous.
  3. Reuse existing OpenTelemetry configuration or install the smallest appropriate SDK and auto-instrumentation.
  4. Store the real ingest endpoint and token only in ignored local configuration.
  5. Configure an explicit service name and service.environment=local.
  6. Wait for provisioning, start or coordinate a local restart, and generate safe read-only application activity.
  7. Verify a fresh trace or application log for that exact service.
  8. Report the event link and changed files, then prepare production configuration or exact deployment instructions.

The agent never calls mutating business endpoints, deploys, commits, pushes, applies infrastructure, or triggers CI/CD. After local success it asks you to review, commit, and deploy, then offers to instrument other services.

Existing instrumentation

Section titled “Existing instrumentation”

The agent scans for existing SDK initialization, exporters, environment variables, and logging bridges before adding packages. It extends working instrumentation instead of creating duplicate providers or exporters. Existing local logging remains intact; OTLP receives an additional copy where the language supports log export.

Local configuration

Section titled “Local configuration”

The local service receives values equivalent to:

Terminal window
OTEL_SERVICE_NAME="my-service"
OTEL_RESOURCE_ATTRIBUTES="service.environment=local"
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443"
OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>"

The endpoint and token come from the protected CLI integration file. They must not appear in tracked files, command output, or deployment manifests. Checked-in examples use placeholders or references to the project’s existing secret mechanism.

Verification

Section titled “Verification”

The agent captures server_time from osuite integration status immediately before the local run, then verifies with:

Terminal window
osuite integration wait \
  --service my-service \
  --environment local \
  --since <server-time>

A fresh trace or real application log completes onboarding. A timeout is resumable: the agent checks exporter errors and configuration without reinstalling the CLI, creating another key, or duplicating instrumentation.

Standard instrumentation mode

Section titled “Standard instrumentation mode”

You can still invoke /osuite-instrument for code-only instrumentation. In standard mode the agent presents its normal implementation plan, applies approved changes, and writes instrumentation.md without running or verifying the application.

Next steps

Section titled “Next steps”