# opentelemetry.sdk._logs package

## Submodules

- opentelemetry.sdk._logs.export
  - `BatchLogRecordProcessor`
    - `BatchLogRecordProcessor.on_emit()`
    - `BatchLogRecordProcessor.shutdown()`
    - `BatchLogRecordProcessor.force_flush()`
  - `ConsoleLogExporter`
  - `ConsoleLogRecordExporter`
    - `ConsoleLogRecordExporter.export()`
    - `ConsoleLogRecordExporter.shutdown()`
    - `ConsoleLogRecordExporter.force_flush()`
  - `LogExporter`
  - `LogRecordExporter`
    - `LogRecordExporter.export()`
    - `LogRecordExporter.shutdown()`
    - `LogRecordExporter.force_flush()`
  - `LogExportResult`
    - `LogExportResult.SUCCESS`
    - `LogExportResult.FAILURE`
  - `LogRecordExportResult`
    - `LogRecordExportResult.SUCCESS`
    - `LogRecordExportResult.FAILURE`
  - `SimpleLogRecordProcessor`
    - `SimpleLogRecordProcessor.on_emit()`
    - `SimpleLogRecordProcessor.shutdown()`
    - `SimpleLogRecordProcessor.force_flush()`
  - `InMemoryLogExporter`
  - `InMemoryLogRecordExporter`
    - `InMemoryLogRecordExporter.clear()`
    - `InMemoryLogRecordExporter.get_finished_logs()`
    - `InMemoryLogRecordExporter.export()`
    - `InMemoryLogRecordExporter.shutdown()`
    - `InMemoryLogRecordExporter.force_flush()`

## Module contents

class opentelemetry.sdk._logs.ConcurrentMultiLogRecordProcessor(max_workers=2)

  Bases: `LogRecordProcessor`

  Implementation of `LogRecordProcessor` that forwards all received events to a list of log processors in parallel.

  Calls to the underlying log processors are forwarded in parallel by submitting them to a thread pool executor and waiting until each log processor finished its work.

  Parameters:

    max_workers (`int`) – The number of threads managed by the thread pool executor and thus defining how many log processors can work in parallel.

  add_log_record_processor(log_record_processor)
  on_emit(log_record)

    Emits the `ReadWriteLogRecord`.

    Implementers should handle any exceptions raised during log processing to prevent application crashes. See the class docstring for details on error handling expectations.

    Return type:

      `None`

  shutdown()

    Called when a `opentelemetry.sdk._logs.Logger` is shutdown

    Return type:

      `None`

  force_flush(timeout_millis=30000)

    Force flush the log processors in parallel.

    Parameters:

      timeout_millis (`int`) – The maximum amount of time to wait for logs to be exported.

    Return type:

      `bool`

    Returns:

      True if all the log processors flushes the logs within timeout, False otherwise.

class opentelemetry.sdk._logs.Logger(resource, multi_log_record_processor, instrumentation_scope, *, logger_metrics, _logger_config)

  Bases: `Logger`

  property instrumentation_scope
  property resource
  emit(record=None, *, timestamp=None, observed_timestamp=None, context=None, severity_number=None, severity_text=None, body=None, attributes=None, event_name=None, exception=None)

    Emits the `ReadWriteLogRecord` by setting instrumentation scope and forwarding to the processor.

    Return type:

      `None`

class opentelemetry.sdk._logs.LoggerProvider(resource=None, shutdown_on_exit=True, multi_log_record_processor=None, *, meter_provider=None, _logger_configurator=None)

  Bases: `LoggerProvider`

  property resource
  get_logger(name, version=None, schema_url=None, attributes=None)

    Returns a `Logger` for use by the given instrumentation library.

    For any two calls with identical parameters, it is undefined whether the same or different `Logger` instances are returned.

    This function may return different `Logger` types (e.g. a no-op logger vs. a functional logger).

    Parameters:

      - name (`str`) –

        The name of the instrumenting module, package or class. This should not be the name of the module, package or class that is instrumented but the name of the code doing the instrumentation. E.g., instead of `"requests"`, use `"opentelemetry.instrumentation.requests"`.

        For log sources which define a logger name (e.g. logging.Logger.name) the Logger Name should be recorded as the instrumentation scope name.

      - version (`str` | `None`) – Optional. The version string of the instrumenting library. Usually this should be the same as `importlib.metadata.version(instrumenting_library_name)`.

      - schema_url (`str` | `None`) – Optional. Specifies the Schema URL of the emitted telemetry.

      - attributes (`Mapping`[`str`, `str` | `bool` | `int` | `float` | `bytes` | `Sequence`[AnyValue] | `Mapping`[`str`, AnyValue] | `None`] | `None`) – Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry.

    Return type:

      `Logger`

  add_log_record_processor(log_record_processor)

    Registers a new `LogRecordProcessor` for this `LoggerProvider` instance.

    The log processors are invoked in the same order they are registered.

  shutdown()

    Shuts down the log processors.

    Return type:

      `None`

  force_flush(timeout_millis=30000)

    Force flush the log processors.

    Parameters:

      timeout_millis (`int`) – The maximum amount of time to wait for logs to be exported.

    Return type:

      `bool`

    Returns:

      True if all the log processors flushes the logs within timeout, False otherwise.

class opentelemetry.sdk._logs.LoggingHandler(level=0, logger_provider=None)

  Bases: `Handler`

  A handler class which writes logging records, in OTLP format, to a network destination or file. Supports signals from the `logging` module. https://docs.python.org/3/library/logging.html

  emit(record)

    Emit a record. Skip emitting if logger is NoOp.

    The record is translated to OTel format, and then sent across the pipeline.

    Return type:

      `None`

  flush()

    Flushes the logging output. Skip flushing if logging_provider has no force_flush method.

    Return type:

      `None`

class opentelemetry.sdk._logs.LogLimits(max_attributes=None, max_attribute_length=None, max_log_record_attributes=None, max_log_record_attribute_length=None)

  Bases: `LogRecordLimits`

class opentelemetry.sdk._logs.LogRecordLimits(max_attributes=None, max_attribute_length=None, max_log_record_attributes=None, max_log_record_attribute_length=None)

  Bases: `object`

  This class is based on a SpanLimits class in the Tracing module.

  This class represents the limits that should be enforced on recorded data such as events, links, attributes etc.

  This class does not enforce any limits itself. It only provides a way to read limits from env, default values and from user provided arguments.

  All limit arguments must be either a non-negative integer or `None`.

  - All limit arguments are optional.

  - If a limit argument is not set, the class will try to read its value from the corresponding environment variable.

  - If the environment variable is not set, the default value, if any, will be used.

  Limit precedence:

  - If a model specific limit is set, it will be used.

  - Else if the corresponding global limit is set, it will be used.

  - Else if the model specific limit has a default value, the default value will be used.

  - Else if the global limit has a default value, the default value will be used.

  Parameters:

    - max_attributes (`int` | `None`) – Maximum number of attributes that can be added to a log record (global fallback). Environment variable: `OTEL_ATTRIBUTE_COUNT_LIMIT` Default: {_DEFAULT_OTEL_ATTRIBUTE_COUNT_LIMIT}

    - max_attribute_length (`int` | `None`) – Maximum length an attribute value can have (global fallback). Values longer than the specified length will be truncated.

    - max_log_record_attributes (`int` | `None`) – Maximum number of attributes that can be added to a log record. Environment variable: `OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT` Falls back to `max_attributes` when unset.

    - max_log_record_attribute_length (`int` | `None`) – Maximum length a log record attribute value can have. Environment variable: `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` Falls back to `max_attribute_length` when unset.

class opentelemetry.sdk._logs.LogRecordProcessor

  Bases: `ABC`

  Interface to hook the log record emitting action.

  Log processors can be registered directly using `LoggerProvider.add_log_record_processor()` and they are invoked in the same order as they were registered.

  Implementers of custom log processors should be aware of the following:

  ### Error Handling

  According to the OpenTelemetry error handling principles, the SDK should not throw unhandled exceptions at runtime. When implementing a custom `LogRecordProcessor`, it is the processor’s responsibility to handle any exceptions that may be raised by the exporter’s `export()` method.

  The `LogRecordExporter.export()` method may raise exceptions (e.g., network errors, timeouts). If these exceptions are not caught, they will propagate up and potentially crash the application.

  Custom processor implementations should wrap exporter calls in a try/except block. See `SimpleLogRecordProcessor` for a reference implementation:

      def on_emit(self, log_record: ReadWriteLogRecord):
          try:
              self._exporter.export((log_record,))
          except Exception:  # pylint: disable=broad-exception-caught
              logger.exception("Exception while exporting logs.")

  The `BatchLogRecordProcessor` handles this implicitly since export operations occur in a background thread where exceptions cannot bubble up to the caller.

  abstractmethod on_emit(log_record)

    Emits the `ReadWriteLogRecord`.

    Implementers should handle any exceptions raised during log processing to prevent application crashes. See the class docstring for details on error handling expectations.

    Return type:

      `None`

  abstractmethod shutdown()

    Called when a `opentelemetry.sdk._logs.Logger` is shutdown

    Return type:

      `None`

  abstractmethod force_flush(timeout_millis=30000)

    Export all the received logs to the configured Exporter that have not yet been exported.

    Parameters:

      timeout_millis (`int`) – The maximum amount of time to wait for logs to be exported.

    Return type:

      `bool`

    Returns:

      False if the timeout is exceeded, True otherwise.

exception opentelemetry.sdk._logs.LogDroppedAttributesWarning(**kwargs)

  Bases: `LogRecordDroppedAttributesWarning`

exception opentelemetry.sdk._logs.LogRecordDroppedAttributesWarning

  Bases: `UserWarning`

  Custom warning to indicate dropped log attributes due to limits.

  This class is used to filter and handle these specific warnings separately from other warnings, ensuring that they are only shown once without interfering with default user warnings.

class opentelemetry.sdk._logs.ReadableLogRecord(log_record, resource, instrumentation_scope=None, limits=None)

  Bases: `object`

  Readable LogRecord should be kept exactly in-sync with ReadWriteLogRecord, only difference is the frozen=True param.

  log_record: LogRecord
  resource: Resource
  instrumentation_scope: InstrumentationScope | None = None
  limits: LogRecordLimits | None = None
  property dropped_attributes: int
  to_json(indent=4)
    Return type:

      `str`

class opentelemetry.sdk._logs.ReadWriteLogRecord(log_record, resource=<opentelemetry.sdk.resources.Resource object>, instrumentation_scope=None, limits=<factory>)

  Bases: `object`

  A ReadWriteLogRecord instance represents an event being logged. ReadWriteLogRecord instances are created and emitted via `Logger` every time something is logged. They contain all the information pertinent to the event being logged.

  log_record: LogRecord
  resource: Resource | None = <opentelemetry.sdk.resources.Resource object>
  instrumentation_scope: InstrumentationScope | None = None
  limits: LogRecordLimits
  property dropped_attributes: int

class opentelemetry.sdk._logs.SynchronousMultiLogRecordProcessor

  Bases: `LogRecordProcessor`

  Implementation of class:`LogRecordProcessor` that forwards all received events to a list of log processors sequentially.

  The underlying log processors are called in sequential order as they were added.

  add_log_record_processor(log_record_processor)

    Adds a Logprocessor to the list of log processors handled by this instance

    Return type:

      `None`

  on_emit(log_record)

    Emits the `ReadWriteLogRecord`.

    Implementers should handle any exceptions raised during log processing to prevent application crashes. See the class docstring for details on error handling expectations.

    Return type:

      `None`

  shutdown()

    Shutdown the log processors one by one

    Return type:

      `None`

  force_flush(timeout_millis=30000)

    Force flush the log processors one by one

    Parameters:

      timeout_millis (`int`) – The maximum amount of time to wait for logs to be exported. If the first n log processors exceeded the timeout then remaining log processors will not be flushed.

    Return type:

      `bool`

    Returns:

      True if all the log processors flushes the logs within timeout, False otherwise.