Resource

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

provide.foundation.logger.otlp.resource

OpenTelemetry Resource creation and service attribute management.

Provides functions for building OTLP Resource instances with standard service attributes according to the OpenTelemetry specification.

Reference: https://opentelemetry.io/docs/specs/otel/resource/semantic_conventions/

Functions

build_resource_attributes

build_resource_attributes(
    service_name: str,
    service_version: str | None = None,
    environment: str | None = None,
    additional_attrs: dict[str, Any] | None = None,
) -> dict[str, Any]

Build resource attributes dictionary.

Creates a dictionary with standard OpenTelemetry resource attributes: - service.name (required) - service.version (optional) - deployment.environment (optional) - Any additional custom attributes

Parameters:

Name	Type	Description	Default
service_name	str	Service name (required)	required
service_version	str | None	Service version (optional)	None
environment	str | None	Deployment environment (dev, staging, prod, etc.)	None
additional_attrs	dict[str, Any] | None	Additional custom resource attributes	None

Returns:

Type	Description
dict[str, Any]	Dictionary of resource attributes

Examples:

>>> build_resource_attributes("my-service")
{'service.name': 'my-service'}

>>> build_resource_attributes(
...     "my-service",
...     service_version="1.2.3",
...     environment="production",
... )
{'service.name': 'my-service', 'service.version': '1.2.3', 'deployment.environment': 'production'}

Source code in provide/foundation/logger/otlp/resource.py

def build_resource_attributes(
    service_name: str,
    service_version: str | None = None,
    environment: str | None = None,
    additional_attrs: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build resource attributes dictionary.

    Creates a dictionary with standard OpenTelemetry resource attributes:
    - service.name (required)
    - service.version (optional)
    - deployment.environment (optional)
    - Any additional custom attributes

    Args:
        service_name: Service name (required)
        service_version: Service version (optional)
        environment: Deployment environment (dev, staging, prod, etc.)
        additional_attrs: Additional custom resource attributes

    Returns:
        Dictionary of resource attributes

    Examples:
        >>> build_resource_attributes("my-service")
        {'service.name': 'my-service'}

        >>> build_resource_attributes(
        ...     "my-service",
        ...     service_version="1.2.3",
        ...     environment="production",
        ... )
        {'service.name': 'my-service', 'service.version': '1.2.3', 'deployment.environment': 'production'}
    """
    attrs: dict[str, Any] = {
        "service.name": service_name,
    }

    if service_version:
        attrs["service.version"] = service_version

    if environment:
        attrs["deployment.environment"] = environment

    if additional_attrs:
        attrs.update(additional_attrs)

    return attrs

create_otlp_resource

create_otlp_resource(
    service_name: str,
    service_version: str | None = None,
    environment: str | None = None,
    additional_attrs: dict[str, Any] | None = None,
) -> Any | None

Create OpenTelemetry Resource instance.

Attempts to create an OpenTelemetry SDK Resource with the provided attributes. Returns None if the OpenTelemetry SDK is not available (optional dependency).

Parameters:

Name	Type	Description	Default
service_name	str	Service name (required)	required
service_version	str | None	Service version (optional)	None
environment	str | None	Deployment environment (optional)	None
additional_attrs	dict[str, Any] | None	Additional custom resource attributes	None

Returns:

Type	Description
Any | None	Resource instance if OpenTelemetry SDK available, None otherwise

Examples:

>>> resource = create_otlp_resource("my-service", service_version="1.0.0")
>>> # Returns Resource instance or None if SDK not installed

>>> resource = create_otlp_resource(
...     "my-service",
...     environment="production",
...     additional_attrs={"team": "platform"},
... )

Source code in provide/foundation/logger/otlp/resource.py

def create_otlp_resource(
    service_name: str,
    service_version: str | None = None,
    environment: str | None = None,
    additional_attrs: dict[str, Any] | None = None,
) -> Any | None:
    """Create OpenTelemetry Resource instance.

    Attempts to create an OpenTelemetry SDK Resource with the provided attributes.
    Returns None if the OpenTelemetry SDK is not available (optional dependency).

    Args:
        service_name: Service name (required)
        service_version: Service version (optional)
        environment: Deployment environment (optional)
        additional_attrs: Additional custom resource attributes

    Returns:
        Resource instance if OpenTelemetry SDK available, None otherwise

    Examples:
        >>> resource = create_otlp_resource("my-service", service_version="1.0.0")
        >>> # Returns Resource instance or None if SDK not installed

        >>> resource = create_otlp_resource(
        ...     "my-service",
        ...     environment="production",
        ...     additional_attrs={"team": "platform"},
        ... )
    """
    try:
        from opentelemetry.sdk.resources import Resource
    except ImportError:
        return None

    attrs = build_resource_attributes(
        service_name=service_name,
        service_version=service_version,
        environment=environment,
        additional_attrs=additional_attrs,
    )

    return Resource.create(attrs)