Monitoring errors and exceptions with OpenTelemetry
Introduction
Exception tracking with OpenTelemetry captures errors as they occur in your application and links them to the distributed trace context. This provides:
- Full stack traces attached to the span where the error occurred.
- Trace correlation linking exceptions to the request flow across services.
- Automatic grouping of similar exceptions in the Uptrace UI.
- Error aggregation showing frequency, affected users, and trends.
Recording exceptions
To record errors and exceptions with OpenTelemetry:
- Get the active span from the current context.
- Call
recordException(or equivalent) to capture the error. - Set the span status to
ERRORwith a descriptive message.
When you record an exception, OpenTelemetry automatically captures these semantic attributes:
| Attribute | Description |
|---|---|
exception.type | The exception class name |
exception.message | The error message |
exception.stacktrace | Full stack trace |
import (
"go.opentelemetry.io/otel/codes"
"go.opentelemetry.io/otel/trace"
)
func doWork(ctx context.Context) error {
// Get the active span from the context.
span := trace.SpanFromContext(ctx)
if err := riskyOperation(); err != nil {
// Record the error as an exception event.
span.RecordError(err)
// Mark the span as failed.
span.SetStatus(codes.Error, err.Error())
return err
}
return nil
}
For language-specific details, see the tracing documentation for your programming language:
Grouping exceptions together
By default, Uptrace groups exceptions by their type and message. To customize grouping, set the grouping.fingerprint attribute to a string or number that identifies similar exceptions:
exception.type = "RuntimeError"
exception.message = "operation failed: 123 456 789"
grouping.fingerprint = "operation failed"
This groups all "operation failed" exceptions together, ignoring the variable parts (123 456 789) in the message. You can also customize grouping rules in the Uptrace UI.
Viewing exceptions
Exceptions appear alongside ERROR logs in Uptrace. To view them:
- Navigate to Traces & Logs in the Uptrace UI.
- Click the Logs button.
- Select the log:error system.
- Filter with
where _event_name = "exception"orwhere exception_type exists.
