Skip to main content
Monitoring is two signals that arrive separately and are read together: metrics answer how much, how often, how slow over long windows, and traces answer where did this one request spend its time. You can send either on its own — neither blocks the other — but the Services and APM pages are built assuming both.
Before you start, you need two values.
  1. Your base endpoint — shown on Get Started in the dashboard. These pages write it as $OIQ_ENDPOINT.
  2. A license key — created in Settings → API keys, starting oiq_. Requires the Admin role. See Create a license key. These pages write it as $OIQ_LICENSE_KEY.
Export both before running anything below:

​
What each page needs

A page with no data is not an error state — it is a page whose signal has not arrived. If Services is empty, no traces carrying service.name have been received inside the current time range.

​
Traces

1

Point the SDK at your endpoint

Every OpenTelemetry SDK reads the same two variables. Set them wherever your process gets its environment — the container spec, the systemd unit, the platform’s config UI.
Use OTLP over HTTP, not gRPC, when you authenticate with an oiq_ key. The two transports are validated differently: the gRPC path on port 4317 expects a signed license JWT, while the HTTP path accepts the dashboard-issued oiq_<hex> keys. Pointing a gRPC exporter at an oiq_ key produces authentication failures that read like a networking problem. Set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf if your SDK defaults to gRPC.
2

Instrument the application

Auto-instrumentation covers the common frameworks without code changes — see Zero-code instrumentation. For anything it does not reach, manual instrumentation adds spans by hand.
3

Confirm the spans landed

Open APM → Services. A service appears the first time a span carrying its service.name is written, and stays listed while data remains inside retention. If it is missing, see Verify your data.

​
Set service.version from the start

service.version is what turns the Versions and Deployments pages from empty into useful, and it is far easier to set now than to backfill later — spans already written keep whatever they were written with. Use whatever your build already knows: a git SHA, a semver tag, an image digest.

​
Metrics

Two sources, both supported, and they can run side by side.
Metrics travel over the same endpoint and headers as traces. If you set the variables above, an SDK or Collector exporting metrics needs nothing further.OpenTelemetry metric names arrive dotted — http.server.request.duration.
Remote-write can be refused by plan. If your plan does not include metrics, the receiver rejects the write rather than accepting and discarding it. The rejection is visible in your Prometheus logs as a non-2xx from the remote-write URL.

​
Projects and APM

APM is the one product where projects narrow what you see. A project maps to a set of services, and the APM pages filter to that set.
  • Pass projectId to look at one project
  • Pass scope=account to read across the whole account
  • Sending neither is refused, deliberately — a request that states no scope is a bug in the caller, and answering account-wide data under one project’s heading is the failure that refusal prevents
Other products — Logs, Infrastructure, Kubernetes, Metrics — are account-scoped and do not take projectId.

​
Cost control before you scale up

Traces are the expensive signal. Decide sampling before you roll instrumentation out widely, not after the first bill:
  • Head sampling in the SDK drops spans at the source and costs nothing to run
  • Tail sampling in the Collector keeps every error and slow trace while dropping the uninteresting majority — more useful, more moving parts
Sampling covers both.

​
Troubleshooting

The spans are not arriving, or they carry no service.name. Check the SDK’s own diagnostic log for exporter errors, then confirm the endpoint and key with Verify your data.
Nearly always one of three things: an oiq_ key sent over gRPC instead of HTTP, the header spelled something other than x-license-key, or a key that was revoked. Header names in gRPC metadata must be lower-case.
Expected. A wide time range is answered from pre-aggregated rollups rather than raw samples, so resolution drops as the window grows. See Exploring metrics.

​
Next

Set up Logs

Correlate logs with the traces you just enabled.

Set up Infrastructure

Hosts, containers and Kubernetes.