# opentelemetry.sdk.resources package

This package implements OpenTelemetry Resources:

> A Resource is an immutable representation of the entity producing telemetry. For example, a process producing telemetry that is running in a container on Kubernetes has a Pod name, it is in a namespace and possibly is part of a Deployment which also has a name. All three of these attributes can be included in the Resource.

Resource objects are created with `Resource.create`, which accepts attributes (key-values). Resources should NOT be created via constructor except by `ResourceDetector` instances which can’t use `Resource.create` to avoid infinite loops. Working with `Resource` objects should only be done via the Resource API methods. Resource attributes can also be passed at process invocation in the `OTEL_RESOURCE_ATTRIBUTES` environment variable. You should register your resource with the `opentelemetry.sdk.trace.TracerProvider` by passing them into their constructors. The `Resource` passed to a provider is available to the exporter, which can send on this information as it sees fit.

    trace.set_tracer_provider(
        TracerProvider(
            resource=Resource.create({
                "service.name": "shoppingcart",
                "service.instance.id": "instance-12",
            }),
        ),
    )
    print(trace.get_tracer_provider().resource.attributes)

    {'telemetry.sdk.language': 'python',
    'telemetry.sdk.name': 'opentelemetry',
    'telemetry.sdk.version': '0.13.dev0',
    'service.name': 'shoppingcart',
    'service.instance.id': 'instance-12'}

Note that the OpenTelemetry project documents certain “standard attributes” that have prescribed semantic meanings, for example `service.name` in the above example.

class opentelemetry.sdk.resources.Resource(attributes, schema_url=None)

  Bases: `object`

  A Resource is an immutable representation of the entity producing telemetry as Attributes.

  static create(attributes=None, schema_url=None)

    Creates a new `Resource` from attributes.

    `ResourceDetector` instances should not call this method.

    Parameters:

      - attributes (`Mapping`[`str`, `str` | `bool` | `int` | `float` | `Sequence`[`str`] | `Sequence`[`bool`] | `Sequence`[`int`] | `Sequence`[`float`]] | `None`) – Optional zero or more key-value pairs.

      - schema_url (`str` | `None`) – Optional URL pointing to the schema

    Return type:

      `Resource`

    Returns:

      The newly-created Resource.

  static get_empty()
    Return type:

      `Resource`

  property attributes: Mapping[str, str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]]
  property schema_url: str
  merge(other)

    Merges this resource and an updating resource into a new `Resource`.

    If a key exists on both the old and updating resource, the value of the updating resource will override the old resource value.

    The updating resource’s `schema_url` will be used only if the old `schema_url` is empty. Attempting to merge two resources with different, non-empty values for `schema_url` will result in an error and return the old resource.

    Parameters:

      other (`Resource`) – The other resource to be merged.

    Return type:

      `Resource`

    Returns:

      The newly-created Resource.

  to_json(indent=4)
    Return type:

      `str`

class opentelemetry.sdk.resources.ResourceDetector(raise_on_error=False)

  Bases: `ABC`

  abstractmethod detect()

    Don’t call `Resource.create` here to avoid an infinite loop, instead instantiate `Resource` directly

    Return type:

      `Resource`

  is_process_dependent()

    Return whether this detector depends on the current process identity.

    Process dependent detectors may return resource attributes that become stale after a process identity change, such as `os.fork()`. Detectors returning `True` should be re-run after such changes so the resulting `Resource` describes the current process.

    Return type:

      `bool`

    Returns:

      `True` if this detector should be re-run after process identity changes otherwise `False`.

class opentelemetry.sdk.resources.OTELResourceDetector(raise_on_error=False)

  Bases: `ResourceDetector`

  detect()

    Don’t call `Resource.create` here to avoid an infinite loop, instead instantiate `Resource` directly

    Return type:

      `Resource`

class opentelemetry.sdk.resources.ProcessResourceDetector(raise_on_error=False, *, include_command_args=False)

  Bases: `ResourceDetector`

  Detect process resource attributes.

  Parameters:

    - raise_on_error (`bool`) – Raise errors from detection instead of logging them.

    - include_command_args (`bool`) – Include `process.command_args` and `process.command_line`. These attributes can contain sensitive command-line values, so they are excluded by default.

  is_process_dependent()

    Return whether this detector depends on the current process identity.

    Process dependent detectors may return resource attributes that become stale after a process identity change, such as `os.fork()`. Detectors returning `True` should be re-run after such changes so the resulting `Resource` describes the current process.

    Return type:

      `bool`

    Returns:

      `True` if this detector should be re-run after process identity changes otherwise `False`.

  detect()

    Don’t call `Resource.create` here to avoid an infinite loop, instead instantiate `Resource` directly

    Return type:

      `Resource`

class opentelemetry.sdk.resources.OsResourceDetector(raise_on_error=False)

  Bases: `ResourceDetector`

  Detect os resources based on Operating System conventions.

  detect()

    Returns a resource with with `os.type` and `os.version`.

    Return type:

      `Resource`

    ## Python’s platform library

    To grab this information, Python’s `platform` does not return what a user might expect it to. Below is a breakdown of its return values in different operating systems.

    Linux

        >>> platform.system()
        'Linux'
        >>> platform.release()
        '6.5.0-35-generic'
        >>> platform.version()
        '#35~22.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue May  7 09:00:52 UTC 2'

    MacOS

        >>> platform.system()
        'Darwin'
        >>> platform.release()
        '23.0.0'
        >>> platform.version()
        'Darwin Kernel Version 23.0.0: Fri Sep 15 14:42:57 PDT 2023; root:xnu-10002.1.13~1/RELEASE_ARM64_T8112'

    Windows

        >>> platform.system()
        'Windows'
        >>> platform.release()
        '2022Server'
        >>> platform.version()
        '10.0.20348'

    FreeBSD

        >>> platform.system()
        'FreeBSD'
        >>> platform.release()
        '14.1-RELEASE'
        >>> platform.version()
        'FreeBSD 14.1-RELEASE releng/14.1-n267679-10e31f0946d8 GENERIC'

    Solaris

        >>> platform.system()
        'SunOS'
        >>> platform.release()
        '5.11'
        >>> platform.version()
        '11.4.0.15.0'

class opentelemetry.sdk.resources.ServiceInstanceIdResourceDetector(raise_on_error=False)

  Bases: `ResourceDetector`

  Detects service.instance.id as a random UUID v4.

  Per the OpenTelemetry specification, SDKs SHOULD generate a random v1/v4 UUID for service.instance.id to uniquely identify each service instance. The ID is shared across all detector instances within the same process and regenerated automatically when the process PID changes (e.g. after a fork).

  Note: because this detector is process dependent, providers refresh it automatically after a fork and merge the newly detected value on top of the existing resource. This means that if a user explicitly sets `service.instance.id` (e.g. via OTEL_RESOURCE_ATTRIBUTES or Resource.create(attributes=…)), that value will be overwritten with a newly generated UUID the next time the process forks. This differs from Resource.create(), which does preserve user supplied overrides.

  is_process_dependent()

    Return whether this detector depends on the current process identity.

    Process dependent detectors may return resource attributes that become stale after a process identity change, such as `os.fork()`. Detectors returning `True` should be re-run after such changes so the resulting `Resource` describes the current process.

    Return type:

      `bool`

    Returns:

      `True` if this detector should be re-run after process identity changes otherwise `False`.

  detect()

    Don’t call `Resource.create` here to avoid an infinite loop, instead instantiate `Resource` directly

    Return type:

      `Resource`

opentelemetry.sdk.resources.get_aggregated_resources(detectors, initial_resource=None, timeout=5)

  Retrieves resources from detectors in the order that they were passed

  Parameters:

    - detectors (`Sequence`[`ResourceDetector`]) – List of resources in order of priority

    - initial_resource (`Resource` | `None`) – Static resource. This has highest priority

    - timeout (`int`) – Number of seconds to wait for each detector to return

  Return type:

    `Resource`

  Returns: