When to use this pattern
Use this pattern when a trace locates a failure or slow boundary but does not contain the full error details.
Investigation flow
- Select the affected trace and note the service, environment, span interval, and identifiers.
- Query structured logs by trace ID. Add span ID when you need one span rather than the whole request.
- Expand the time range only enough to account for clock skew or delayed records.
- Read the errors in execution context, then compare a healthy request to test the explanation.
Required fields
| Field or dimension | Purpose |
|---|---|
| trace_id | Exact request-level match across log records. |
| span_id | Optional narrower match to the selected span. |
| service and environment | Exclude records from another workload or environment. |
Worked example: A timeout with an unexpected local cause
Illustrative scenario
A payment client span lasts two seconds and ends in an error. Matching checkout logs show that the connection pool was exhausted before the request reached the provider. The trace identified the boundary; the logs distinguish local waiting from provider failure.
| Evidence | Observation |
|---|---|
| Trace | checkout, production, trace 4bf92f…, span 00f067… |
| Log | Same trace and span; message: connection pool acquire timeout |
| Next check | Compare pool occupancy and a successful checkout in the same version. |
Limitations and false matches
- No matching records may mean missing ID injection, field remapping, or shorter log retention.
- A recorded log can reference a trace removed by sampling or retention.
- Workflow IDs and trace IDs serve different scopes; do not silently treat them as interchangeable.
Verification checklist
- Generate a known request and confirm both its trace and log record exist.
- Open the span-to-log link and confirm service, environment, and identifiers match.
- Test a request in a second environment to detect overly broad queries.
Supported by
Documented examples, not an exhaustive compatibility list. Features require suitable instrumentation and configuration; availability can depend on the runtime, backend, and subscription.
- OpenTelemetry — Log records can include trace and span identifiers.
- Grafana with Tempo and Loki — Configured span links query related log records.
- Datadog — Trace ID injection connects application logs with APM traces.
Related signals
Related concepts
Related patterns
- Metrics to Traces
- Services to Dependencies
- Service to Database
- User Session to Backend Trace
- Queue Producer to Consumer
Related guides
- What is Observability?
- What is MTTR?
- OpenTelemetry: Logs to Traces in Python
- Troubleshoot: Log Trace ID Not Found
FAQ
Must every log have a span ID?
No. Background or startup logs may have no active span. Preserve available context and avoid inventing a span association.