# opentelemetry.trace.span

class opentelemetry.trace.span.Span

  Bases: `ABC`

  A span represents a single operation within a trace.

  abstractmethod end(end_time=None)

    Sets the current time as the span’s end time.

    The span’s end time is the wall time at which the operation finished.

    Only the first call to `end` should modify the span, and implementations are free to ignore or raise on further calls.

    Return type:

      `None`

  abstractmethod get_span_context()

    Gets the span’s SpanContext.

    Get an immutable, serializable identifier for this span that can be used to create new child spans.

    Return type:

      `SpanContext`

    Returns:

      A `opentelemetry.trace.SpanContext` with a copy of this span’s immutable state.

  abstractmethod set_attributes(attributes)

    Sets Attributes.

    Sets Attributes with the key and value passed as arguments dict.

    Note: The behavior of `None` value attributes is undefined, and hence strongly discouraged. It is also preferred to set attributes at span creation, instead of calling this method later since samplers can only consider information already present during span creation.

    Return type:

      `None`

  abstractmethod set_attribute(key, value)

    Sets an Attribute.

    Sets a single Attribute with the key and value passed as arguments.

    Note: The behavior of `None` value attributes is undefined, and hence strongly discouraged. It is also preferred to set attributes at span creation, instead of calling this method later since samplers can only consider information already present during span creation.

    Return type:

      `None`

  abstractmethod add_event(name, attributes=None, timestamp=None)

    Adds an `Event`.

    Adds a single `Event` with the name and, optionally, a timestamp and attributes passed as arguments. Implementations should generate a timestamp if the `timestamp` argument is omitted.

    Return type:

      `None`

  add_link(context, attributes=None)

    Adds a `Link`.

    Adds a single `Link` with the `SpanContext` of the span to link to and, optionally, attributes passed as arguments. Implementations may ignore calls with an invalid span context if both attributes and TraceState are empty.

    Note: It is preferred to add links at span creation, instead of calling this method later since samplers can only consider information already present during span creation.

    Return type:

      `None`

  abstractmethod update_name(name)

    Updates the `Span` name.

    This will override the name provided via `opentelemetry.trace.Tracer.start_span()`.

    Upon this update, any sampling behavior based on Span name will depend on the implementation.

    Return type:

      `None`

  abstractmethod is_recording()

    Returns whether this span will be recorded.

    Returns true if this Span is active and recording information like events with the add_event operation and attributes using set_attribute.

    Return type:

      `bool`

  abstractmethod set_status(status, description=None)

    Sets the Status of the Span. If used, this will override the default Span status.

    Return type:

      `None`

  abstractmethod record_exception(exception, attributes=None, timestamp=None, escaped=False)

    Records an exception as a span event.

    Return type:

      `None`

class opentelemetry.trace.span.TraceFlags

  Bases: `int`

  A bitmask that represents options specific to the trace.

  The only supported option is the “sampled” flag (`0x01`). If set, this flag indicates that the trace may have been sampled upstream.

  See the W3C Trace Context - Traceparent spec for details.

  DEFAULT = 0
  SAMPLED = 1
  classmethod get_default()
    Return type:

      `TraceFlags`

  property sampled: bool

class opentelemetry.trace.span.TraceState(entries=None)

  Bases: `Mapping`[`str`, `str`]

  A list of key-value pairs representing vendor-specific trace info.

  Keys and values are strings of up to 256 printable US-ASCII characters. Implementations should conform to the W3C Trace Context - Tracestate spec, which describes additional restrictions on valid field values.

  add(key, value)

    Adds a key-value pair to tracestate. The provided pair should adhere to w3c tracestate identifiers format.

    Parameters:

      - key (`str`) – A valid tracestate key to add

      - value (`str`) – A valid tracestate value to add

    Return type:

      `TraceState`

    Returns:

      A new TraceState with the modifications applied.

      If the provided key-value pair is invalid or results in tracestate that violates tracecontext specification, they are discarded and same tracestate will be returned.

  update(key, value)

    Updates a key-value pair in tracestate. The provided pair should adhere to w3c tracestate identifiers format.

    Parameters:

      - key (`str`) – A valid tracestate key to update

      - value (`str`) – A valid tracestate value to update for key

    Return type:

      `TraceState`

    Returns:

      A new TraceState with the modifications applied.

      If the provided key-value pair is invalid or results in tracestate that violates tracecontext specification, they are discarded and same tracestate will be returned.

  delete(key)

    Deletes a key-value from tracestate.

    Parameters:

      key (`str`) – A valid tracestate key to remove key-value pair from tracestate

    Return type:

      `TraceState`

    Returns:

      A new TraceState with the modifications applied.

      If the provided key-value pair is invalid or results in tracestate that violates tracecontext specification, they are discarded and same tracestate will be returned.

  to_header()

    Creates a w3c tracestate header from a TraceState.

    Return type:

      `str`

    Returns:

      A string that adheres to the w3c tracestate header format.

  classmethod from_header(header_list)

    Parses one or more w3c tracestate header into a TraceState.

    Parameters:

      header_list (`List`[`str`]) – one or more w3c tracestate headers.

    Return type:

      `TraceState`

    Returns:

      A valid TraceState that contains values extracted from the tracestate header.

      If the format of one headers is illegal, all values will be discarded and an empty tracestate will be returned.

      If the number of keys is beyond the maximum, all values will be discarded and an empty tracestate will be returned.

  classmethod get_default()
    Return type:

      `TraceState`

  keys()
    Return type:

      `KeysView`[`str`]

  items()
    Return type:

      `ItemsView`[`str`, `str`]

  values()
    Return type:

      `ValuesView`[`str`]

class opentelemetry.trace.span.SpanContext(trace_id: int, span_id: int, is_remote: bool, trace_flags: TraceFlags | None = 0, trace_state: TraceState | None = [])

  Bases: `Tuple`[`int`, `int`, `bool`, `TraceFlags`, `TraceState`, `bool`]

  The state of a Span to propagate between processes.

  This class includes the immutable attributes of a `Span` that must be propagated to a span’s children and across process boundaries.

  Parameters:

    - trace_id – The ID of the trace that this span belongs to.

    - span_id – This span’s ID.

    - is_remote – True if propagated from a remote parent.

    - trace_flags – Trace options to propagate.

    - trace_state – Tracing-system-specific info to propagate.

  property trace_id: int
  property span_id: int
  property is_remote: bool
  property trace_flags: TraceFlags
  property trace_state: TraceState
  property is_valid: bool

class opentelemetry.trace.span.NonRecordingSpan(context)

  Bases: `Span`

  The Span that is used when no Span implementation is available.

  All operations are no-op except context propagation.

  get_span_context()

    Gets the span’s SpanContext.

    Get an immutable, serializable identifier for this span that can be used to create new child spans.

    Return type:

      `SpanContext`

    Returns:

      A `opentelemetry.trace.SpanContext` with a copy of this span’s immutable state.

  is_recording()

    Returns whether this span will be recorded.

    Returns true if this Span is active and recording information like events with the add_event operation and attributes using set_attribute.

    Return type:

      `bool`

  end(end_time=None)

    Sets the current time as the span’s end time.

    The span’s end time is the wall time at which the operation finished.

    Only the first call to `end` should modify the span, and implementations are free to ignore or raise on further calls.

    Return type:

      `None`

  set_attributes(attributes)

    Sets Attributes.

    Sets Attributes with the key and value passed as arguments dict.

    Note: The behavior of `None` value attributes is undefined, and hence strongly discouraged. It is also preferred to set attributes at span creation, instead of calling this method later since samplers can only consider information already present during span creation.

    Return type:

      `None`

  set_attribute(key, value)

    Sets an Attribute.

    Sets a single Attribute with the key and value passed as arguments.

    Note: The behavior of `None` value attributes is undefined, and hence strongly discouraged. It is also preferred to set attributes at span creation, instead of calling this method later since samplers can only consider information already present during span creation.

    Return type:

      `None`

  add_event(name, attributes=None, timestamp=None)

    Adds an `Event`.

    Adds a single `Event` with the name and, optionally, a timestamp and attributes passed as arguments. Implementations should generate a timestamp if the `timestamp` argument is omitted.

    Return type:

      `None`

  add_link(context, attributes=None)

    Adds a `Link`.

    Adds a single `Link` with the `SpanContext` of the span to link to and, optionally, attributes passed as arguments. Implementations may ignore calls with an invalid span context if both attributes and TraceState are empty.

    Note: It is preferred to add links at span creation, instead of calling this method later since samplers can only consider information already present during span creation.

    Return type:

      `None`

  update_name(name)

    Updates the `Span` name.

    This will override the name provided via `opentelemetry.trace.Tracer.start_span()`.

    Upon this update, any sampling behavior based on Span name will depend on the implementation.

    Return type:

      `None`

  set_status(status, description=None)

    Sets the Status of the Span. If used, this will override the default Span status.

    Return type:

      `None`

  record_exception(exception, attributes=None, timestamp=None, escaped=False)

    Records an exception as a span event.

    Return type:

      `None`

opentelemetry.trace.span.format_trace_id(trace_id)

  Convenience trace ID formatting method :type trace_id: `int` :param trace_id: Trace ID int

  Return type:

    `str`

  Returns:

    The trace ID (16 bytes) cast to a 32-character hexadecimal string

opentelemetry.trace.span.format_span_id(span_id)

  Convenience span ID formatting method :type span_id: `int` :param span_id: Span ID int

  Return type:

    `str`

  Returns:

    The span ID (8 bytes) cast to a 16-character hexadecimal string