Getting Started

Osuite receives all telemetry over the OpenTelemetry Protocol (OTLP). Getting your first data in takes under ten minutes: create an account and grab your ingest token, then choose one of two paths to send telemetry.

The two paths are not a trace-versus-logs choice — both carry every signal. They differ by where the work happens:

• Path A — the AI agent instruments an application that does not emit OpenTelemetry yet. It writes the SDK setup into your code for you.
• Path B — the OpenTelemetry Collector receives OTLP from services you have already instrumented and from your infrastructure, and forwards it to Osuite.

If your services already export OpenTelemetry, you need neither path — see the note in Step 2.

Step 1: Create your account

Sign up at osuite.io. After you sign up you are issued an ingest token and a region-specific ingest endpoint. The endpoint is tied to your region and looks like this:

ingest.<region>.osuite.io:443

You can find or rotate the ingest token in the Osuite UI under Settings → API Keys. For how regions and endpoints work, see Architecture.

Step 2: Send your first telemetry

Already using OpenTelemetry?

You do not need either path below. Point your existing OTLP exporter — SDK or Collector — at ingest.<region>.osuite.io:443 with your ingest token. See Already using OpenTelemetry.

Path A: Instrument your app with the AI agent

Use this when a service is not emitting telemetry yet. The Instrumentation Agent runs in your AI IDE, detects your language and framework, installs the right OpenTelemetry packages, writes the SDK init module, and sets the environment variables.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument

First time on this machine? Run osuite init-ai once to install the agent skills — see AI agent setup.

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

For the full walkthrough, including the environment variables the agent writes into your project, see the Instrumentation Agent guide.

Path B: Deploy the OpenTelemetry Collector

Use this to forward OTLP from services you have already instrumented, and to collect logs and metrics from your hosts and containers. Save the following as otel-collector.yaml:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 5s
    send_batch_size: 1000

exporters:
  otlp/osuite:
    endpoint: ingest.<region>.osuite.io:443
    tls:
      insecure: false
    headers:
      x-osuite-ingest-token: <your-ingest-token>

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/osuite]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/osuite]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/osuite]

Replace <region> with your region and <your-ingest-token> with the token from Step 1. Run the Collector:

docker run --rm \
  -p 4317:4317 -p 4318:4318 \
  -v $(pwd)/otel-collector.yaml:/etc/otel-collector.yaml \
  otel/opentelemetry-collector-contrib:latest \
  --config /etc/otel-collector.yaml

Point your instrumented services at the Collector’s OTLP endpoint (http://<collector-host>:4318). The Collector batches and forwards every signal — traces, logs, and metrics — to your Osuite region. To add host and Kubernetes telemetry, wire the relevant receivers into the pipelines: see Infrastructure and Logs.

Step 3: Verify data is arriving

Verify in Osuite

What you should see

Generate some traffic against your service, then open the Osuite UI. Within a minute you should see traces under Traces, logs streaming under Logs, and metrics under Dashboards → Explore metrics.

If nothing appears after 60 seconds:

• Confirm the ingest token is correct and has not been rotated.
• Confirm your app or Collector can reach ingest.<region>.osuite.io on port 443 (not blocked by a firewall).
• Confirm your application is actually handling requests — some frameworks only emit spans when a request is served.

Next steps

With data flowing, explore the platform:

• Concepts — OTLP, the three signals, and how Osuite correlates them
• Architecture — how telemetry flows into Osuite, and regions
• APM & Tracing — golden signals and per-request traces across services
• Logs — collect and search logs from applications and servers
• Infrastructure — monitor hosts and Kubernetes via the Collector
• Investigation Agent — diagnose incidents from your IDE once telemetry is flowing
• Alerts — PromQL-based alerts with Slack, Opsgenie, Zenduty, and PagerDuty notifications