Skip to content
Pydantic Docs

Pydantic Logfire Types Reference

SpanLevel

A convenience class for comparing span/log levels.

Can be compared to log level names (strings) such as ‘info’ or ‘error’ using <, >, <=, or >=, so e.g. level >= 'error' is valid.

Will raise an exception if compared to a non-string or an invalid level name.

Attributes

number

The raw numeric value of the level. Higher values are more severe.

Type: int

name

The human-readable name of the level, or None if the number is invalid.

Type: LevelName | None

Methods

from_span

@classmethod

def from_span(cls, span: ReadableSpan) -> SpanLevel

Create a SpanLevel from an OpenTelemetry span.

If the span has no level set, defaults to ‘info’.

Returns

SpanLevel

ExceptionCallbackHelper

Helper object passed to the exception callback.

This is experimental and may change significantly in future releases.

Attributes

level

Convenient way to see and compare the level of the span.

  • When using logfire.span or logfire.exception, this is usually error.
  • Spans created directly by an OpenTelemetry tracer (e.g. from any logfire.instrument_*() method) typically don’t have a level set, so this will return the default of info, but level_is_unset will be True.
  • Will be a different level if this is created by e.g. logfire.info(..., _exc_info=True).

Type: SpanLevel

level_is_unset

Determine if the level has not been explicitly set on the span (yet).

For messy technical reasons, this is typically True for spans created directly by an OpenTelemetry tracer (e.g. from any logfire.instrument_*() method) although the level will usually still eventually be error by the time it’s exported.

Spans created by logfire.span() get the level set to error immediately when an exception passes through, so this will be False in that case.

This is also typically True when calling span.record_exception() directly on any span instead of letting an exception bubble through.

Type: bool

parent_span

The parent span of the span the exception was recorded on.

This is None if there is no parent span, or if the parent span is in a different process.

Type: ReadableSpan | None

issue_fingerprint_source

Returns a string that will be hashed to create the issue fingerprint.

By default this is a canonical representation of the exception traceback:

  • The source line is used, but not the line number, so that changes elsewhere in a file are irrelevant.
  • The module is used instead of the filename.
  • The same line appearing multiple times in a stack is ignored.
  • Exception group sub-exceptions are sorted and deduplicated.
  • If the exception has a cause or (not suppressed) context, it is included in the representation.
  • Cause and context are treated as different.

Type: str

create_issue

Whether to create an issue for this exception.

By default, issues are only created for exceptions on spans where:

  • The level is ‘error’ or higher or is unset (see level_is_unset for details),
  • No parent span exists in the current process,

Type: bool

Methods

no_record_exception 

def no_record_exception() -> None

Call this method to prevent recording the exception on the span.

This improves performance and reduces noise in Logfire. This will also prevent creating an issue for this exception. The span itself will still be recorded, just without the exception information. This doesn’t affect the level of the span, it will still be ‘error’ by default. To still record exception info without creating an issue, use helper.create_issue = False instead. To still record the exception info but at a different level, use helper.level = 'warning' or some other level instead.

Returns

None

ExceptionCallback

This is experimental and may change significantly in future releases.

Usage:

def my_callback(helper: logfire.types.ExceptionCallbackHelper):

Use helper here to customize how an exception is recorded on a span.

…

logfire.configure(advanced=logfire.AdvancedOptions(exception_callback=my_callback))

Note: When using ProcessPoolExecutor, the exception callback must be defined at the module level (not as a local function) to be picklable. Local functions will be excluded from the serialized configuration sent to child processes. See the distributed tracing guide for more details.

Examples:

Set the level:

helper.level = ‘warning’

Make the issue fingerprint less granular:

if isinstance(helper.exception, MyCustomError): helper.issue_fingerprint_source = “MyCustomError”

Make the issue fingerprint more granular:

if helper.create_issue: helper.issue_fingerprint_source += str(helper.exception)

Create issues for all exceptions, even warnings:

helper.create_issue = True

Don’t record the exception on the span:

helper.no_record_exception()

Default: Callable[[ExceptionCallbackHelper], None]