Add Events, Exceptions and Status to Spans

OTEL supports Events, Excpetios and Status on spans.

• Basic Event Logging in OpenTelemetry: Logs key events during the execution of a code path to a trace span, providing insights into specific actions within your application's workflow.

• Error Handling with Span Status in OpenTelemetry: Marks a trace span with an error status when an exception occurs, helping to identify and troubleshoot issues in distributed systems.

• Error Handling and Exception Recording in OpenTelemetry: Sets a span's status to error and records detailed information about exceptions, offering a comprehensive view of failures for more effective debugging.

Adding events

Events are human-readable messages that represent "something happening" at a particular moment during the lifetime of a span. You can think of it as a primitive log.

Python

from opentelemetry import trace

current_span = trace.get_current_span()

current_span.add_event("Gonna try it!")

# Do the thing

current_span.add_event("Did it!")

JS/TS

import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('default');
const currentSpan = tracer.getCurrentSpan();

if (currentSpan) {
    currentSpan.addEvent('Gonna try it!');

    // Do the thing

    currentSpan.addEvent('Did it!');
}

Java

singleAttrSpan.addEvent("Doing Something");
singleAttrSpan.addEvent("Doing another thing");
singleAttrSpan.end();

Set span status

The span status allows you to signal the success or failure of the code executed within the span.

Python

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

current_span = trace.get_current_span()

try:
    # something that might fail
except:
    current_span.set_status(Status(StatusCode.ERROR))

JS/TS

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('default');
const currentSpan = tracer.getCurrentSpan();

try {
    // something that might fail
} catch (error) {
    if (currentSpan) {
        currentSpan.setStatus({ code: SpanStatusCode.ERROR });
    }
}

Record exceptions in spans

It can be a good idea to record exceptions when they happen. It’s recommended to do this in conjunction with setting span status.

Python

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

current_span = trace.get_current_span()

try:
    # something that might fail

# Consider catching a more specific exception in your code
except Exception as ex:
    current_span.set_status(Status(StatusCode.ERROR))
    current_span.record_exception(ex)

JS/TS

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('default');
const currentSpan = tracer.getCurrentSpan();

try {
    // something that might fail

// Consider catching a more specific error in your code
} catch (ex) {
    if (currentSpan) {
        currentSpan.setStatus({ code: SpanStatusCode.ERROR });
        currentSpan.recordException(ex);
    }
}

Span events

A Span Event is a human-readable message on an Span that represents a discrete event with no duration that can be tracked by a single timestamp. You can think of it like a primitive log.

span.addEvent('Doing something');

const result = doWork();

You can also create Span Events with additional Attributes

span.addEvent('some log', {
  'log.severity': 'error',
  'log.message': 'Data not found',
  'request.id': requestId,
});

Span Status

A Status can be set on a Span, typically used to specify that a Span has not completed successfully - Error. By default, all spans are Unset, which means a span completed without error. The Ok status is reserved for when you need to explicitly mark a span as successful rather than stick with the default of Unset (i.e., “without error”).

The status can be set at any time before the span is finished.

import opentelemetry, { SpanStatusCode } from '@opentelemetry/api';

// ...

tracer.startActiveSpan('app.doWork', (span) => {
  for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {
    if (i > 10000) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: 'Error',
      });
    }
  }

  span.end();
});

Recording exceptions It can be a good idea to record exceptions when they happen. It’s recommended to do this in conjunction with setting span status.

import opentelemetry, { SpanStatusCode } from '@opentelemetry/api';

// ...

try {
  doWork();
} catch (ex) {
  span.recordException(ex);
  span.setStatus({ code: SpanStatusCode.ERROR });
}