Set up Logs

Logs arrive over the same OTLP endpoint as everything else. What separates a useful log setup from a noisy one is not the transport — it is which fields you populate on the way in, because those are what search, filtering and trace correlation are built on.

Before you start, you need two values.

Your base endpoint — shown on Get Started in the dashboard. These pages write it as $OIQ_ENDPOINT.
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:

export OIQ_ENDPOINT="https://app.aiaxoniq.com/otlp"   # or your own
export OIQ_LICENSE_KEY="oiq_..."

The fields that matter

Every log line is stored with these, and each one drives something you can do with it later:

Field	What it enables	Where it comes from
`body`	Full-text search	The log message
`service_name`	Filtering by service; the link to Services and APM	`service.name` resource attribute
`severity_text` / `severity_number`	Level filters, error counts	The SDK’s log level mapping
`trace_id` / `span_id`	Jump from a log line to its trace	Automatic when logs are emitted inside an active span
`host_name`	Filtering by host; the link to Infrastructure	`host.name` resource attribute
`service_version`	Comparing log volume across releases	`service.version` resource attribute
`attributes`	Structured filtering on your own fields	Whatever you attach to the record
`resource_attributes`	Environment, region, cluster filtering	The resource

Trace correlation is free, but only if the log is emitted inside the span. trace_id and span_id are populated by the SDK’s log appender from the active context. A line written from a background goroutine or a detached worker has no active span and lands with empty ids — which is correct, not a bug, but it will not link.

Sending logs

From the application
From files or stdout
System logs

Use your language’s OpenTelemetry log appender so the SDK attaches trace context automatically. The endpoint and headers are the same two variables used for traces and metrics:

export OTEL_EXPORTER_OTLP_ENDPOINT="$OIQ_ENDPOINT"
export OTEL_EXPORTER_OTLP_HEADERS="x-license-key=$OIQ_LICENSE_KEY"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_SERVICE_NAME="checkout-api"

Use OTLP over HTTP with an oiq_ key. The gRPC path expects a signed license JWT and will reject a dashboard-issued key with an authentication error that looks like a network problem.

Where you cannot change the application, the Collector reads logs from disk or from the container runtime and adds the resource attributes:

receivers:
  filelog:
    include: [/var/log/myapp/*.log]
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.ts
          layout: "%Y-%m-%dT%H:%M:%S.%LZ"
        severity:
          parse_from: attributes.level

processors:
  resource:
    attributes:
      - key: service.name
        value: checkout-api
        action: upsert

exporters:
  otlphttp:
    endpoint: "$OIQ_ENDPOINT"
    headers:
      x-license-key: "$OIQ_LICENSE_KEY"

service:
  pipelines:
    logs:
      receivers: [filelog]
      processors: [resource]
      exporters: [otlphttp]

Logs collected this way carry no trace context unless the application already prints trace_id into the line and you map it with an operator.

On a Linux host, the journald receiver picks up systemd unit logs. The Linux VM page has the full collector unit, including keeping the key out of the config file.

Parse before you send, not after

A log line stored as one opaque string is searchable but not filterable. Parsing JSON at the Collector — or emitting structured logs from the application — turns fields into attributes you can filter on directly, which is both faster and cheaper than a full-text scan. The rule of thumb: anything you will ever want to filter by should be an attribute; anything you will only ever read can stay in the body.

What you get once logs arrive

Search

Full-text over the body, plus field filters and a query syntax for combining them.

Live tail

A streaming view of lines as they arrive, filtered the same way.

Patterns

Clusters near-identical lines so a million repeats read as one pattern with a count.

Retention

Logs are kept for the retention window on your plan — 30 days unless your plan says otherwise. Retention is applied on read as well as on storage, so a search over a wider range than your plan allows returns what is inside the window rather than erroring.

Volume control

Logs are usually the highest-volume signal. Two levers, in order of effect:

Do not ship debug level from production. Filter at the source, where it costs nothing.
Drop known-noisy lines at the Collector with a filter processor — health check hits, readiness probes, chatty third-party libraries.

Sampling logs is a poor third option: unlike traces, a sampled log set answers “how many times did this happen” wrongly.

Troubleshooting

Logs arrive but the Logs page shows no service

The resource has no service.name. Add it with a resource processor in the Collector, or set OTEL_SERVICE_NAME in the application.

A log line will not link to its trace

Check that trace_id is non-empty on the line. If it is empty, the log was emitted outside an active span — common in startup code, background jobs and exception handlers that run after the span has ended.

Timestamps are wrong or clustered at ingest time

The parser did not find the timestamp field, so the receive time was used instead. Check the timestamp.parse_from path and the layout string against an actual line.

Set up Monitoring

Metrics and traces, so log lines have traces to link to.

Set up Infrastructure

Hosts, containers and Kubernetes.

Overview

Set up a signal

Platforms

OpenTelemetry

Other sources

The fields that matter

Sending logs

Parse before you send, not after

What you get once logs arrive

Search

Live tail

Patterns

Retention

Volume control

Troubleshooting

Next

Set up Monitoring

Set up Infrastructure

​The fields that matter

​Sending logs

​Parse before you send, not after

​What you get once logs arrive

Search

Live tail

Patterns

​Retention

​Volume control

​Troubleshooting

​Next

Set up Monitoring

Set up Infrastructure

The fields that matter

Sending logs

Parse before you send, not after

What you get once logs arrive

Retention

Volume control

Troubleshooting

Next