rebrandly-otel 0.2.16__py3-none-any.whl → 0.2.19__py3-none-any.whl

rebrandly_otel/span_attributes_processor.py

@@ -0,0 +1,106 @@
+"""
+Span Attributes Processor for Rebrandly OTEL SDK
+Automatically adds attributes from OTEL_SPAN_ATTRIBUTES environment variable to all spans
+"""
+
+import os
+from typing import Optional
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span
+from opentelemetry.sdk.trace.export import SpanProcessor
+
+
+class SpanAttributesProcessor(SpanProcessor):
+    """
+    Span processor that automatically adds attributes from OTEL_SPAN_ATTRIBUTES
+    environment variable to all spans at creation time.
+    """
+
+    def __init__(self):
+        """Initialize the processor and parse OTEL_SPAN_ATTRIBUTES."""
+        self.name = 'SpanAttributesProcessor'
+        self.span_attributes = self._parse_span_attributes()
+
+        # Log parsed attributes in debug mode
+        if os.environ.get('OTEL_DEBUG', 'false').lower() == 'true' and self.span_attributes:
+            print(f'[SpanAttributesProcessor] Parsed OTEL_SPAN_ATTRIBUTES: {self.span_attributes}')
+
+    def _parse_span_attributes(self) -> dict:
+        """
+        Parse OTEL_SPAN_ATTRIBUTES environment variable.
+        Format: key1=value1,key2=value2
+
+        Returns:
+            Dictionary of parsed attributes as key-value pairs
+        """
+        attributes = {}
+        otel_span_attrs = os.environ.get('OTEL_SPAN_ATTRIBUTES', None)
+
+        if not otel_span_attrs or otel_span_attrs.strip() == '':
+            return attributes
+
+        try:
+            pairs = otel_span_attrs.split(',')
+            for attr in pairs:
+                trimmed_attr = attr.strip()
+                if trimmed_attr and '=' in trimmed_attr:
+                    # Split on first '=' only, in case value contains '='
+                    key, value = trimmed_attr.split('=', 1)
+                    key = key.strip()
+                    value = value.strip()
+                    if key:
+                        attributes[key] = value
+        except Exception as e:
+            print(f'[SpanAttributesProcessor] Warning: Invalid OTEL_SPAN_ATTRIBUTES value: {e}')
+
+        return attributes
+
+    def on_start(self, span: Span, parent_context: Optional[Context] = None) -> None:
+        """
+        Called when a span is started.
+        Adds configured attributes to the span.
+
+        Args:
+            span: The span that was just started
+            parent_context: The parent context (optional)
+        """
+        try:
+            # Add all parsed attributes to the span
+            if self.span_attributes:
+                for key, value in self.span_attributes.items():
+                    span.set_attribute(key, value)
+        except Exception as e:
+            # Fail silently to avoid breaking the entire tracing pipeline
+            # Log only in debug mode to avoid noise
+            if os.environ.get('OTEL_DEBUG', 'false').lower() == 'true':
+                print(f'[SpanAttributesProcessor] Error processing span: {e}')
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """
+        Called when a span is ended.
+        No-op for this processor.
+
+        Args:
+            span: The span that was just ended
+        """
+        pass
+
+    def shutdown(self) -> None:
+        """
+        Shutdown the processor.
+        No-op for this processor.
+        """
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        """
+        Force flush the processor.
+        No-op for this processor.
+
+        Args:
+            timeout_millis: Maximum time to wait for flush in milliseconds
+
+        Returns:
+            Always returns True as there's nothing to flush
+        """
+        return True

rebrandly_otel/traces.py

@@ -12,6 +12,7 @@ from opentelemetry.sdk.trace.export import (
 )
 
 from .otel_utils import *
+from .span_attributes_processor import SpanAttributesProcessor
 
 class RebrandlyTracer:
     """Wrapper for OpenTelemetry tracing with Rebrandly-specific features."""
@@ -26,6 +27,9 @@ class RebrandlyTracer:
         # Create provider with resource
         self._provider = TracerProvider(resource=create_resource())
 
+        # Add span attributes processor to automatically add OTEL_SPAN_ATTRIBUTES to all spans
+        self._provider.add_span_processor(SpanAttributesProcessor())
+
         # Add console exporter for local debugging
         if is_otel_debug():
             console_exporter = ConsoleSpanExporter()

{rebrandly_otel-0.2.16.dist-info → rebrandly_otel-0.2.19.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rebrandly_otel
-Version: 0.2.16
+Version: 0.2.19
 Summary: Python OTEL wrapper by Rebrandly
 Home-page: https://github.com/rebrandly/rebrandly-otel-python
 Author: Antonio Romano
@@ -51,14 +51,16 @@ pip install rebrandly-otel
 
 The SDK is configured through environment variables:
 
-| Variable                           | Description | Default |
-|------------------------------------|-------------|---------|
-| `OTEL_SERVICE_NAME`                | Service identifier | `default-service-python` |
-| `OTEL_SERVICE_VERSION`             | Service version | `1.0.0` |
-| `OTEL_EXPORTER_OTLP_ENDPOINT`      | OTLP collector endpoint | `None` |
-| `OTEL_DEBUG`                       | Enable console debugging | `false` |
-| `BATCH_EXPORT_TIME_MILLIS`         | Batch export interval | `100` |
-| `ENV` or `ENVIRONMENT` or `NODE_ENV`       | Deployment environment | `local` |
+| Variable                           | Description | Default                         |
+|------------------------------------|-------------|---------------------------------|
+| `OTEL_SERVICE_NAME`                | Service identifier | `default-service-python`        |
+| `OTEL_SERVICE_VERSION`             | Service version | `1.0.0`                         |
+| `OTEL_SERVICE_APPLICATION`         | Application namespace (groups multiple services under one application) | Fallback to `OTEL_SERVICE_NAME` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT`      | OTLP collector endpoint | `None`                          |
+| `OTEL_DEBUG`                       | Enable console debugging | `false`                         |
+| `OTEL_SPAN_ATTRIBUTES`             | Attributes automatically added to all spans (format: `key1=value1,key2=value2`) | `None`                          |
+| `BATCH_EXPORT_TIME_MILLIS`         | Batch export interval | `100`                           |
+| `ENV` or `ENVIRONMENT` or `NODE_ENV`       | Deployment environment | `local`                         |
 
 ## Core Components
 
@@ -146,6 +148,67 @@ Lambda spans automatically include:
 - `cloud.provider`: Always "aws" for Lambda
 - `cloud.platform`: Always "aws_lambda" for Lambda
 
+## Automatic Span Attributes
+
+The SDK supports automatically adding custom attributes to all spans via the `OTEL_SPAN_ATTRIBUTES` environment variable. This is useful for adding metadata that applies to all telemetry in a service, such as team ownership, deployment environment, or version information.
+
+### Configuration
+
+Set the `OTEL_SPAN_ATTRIBUTES` environment variable with a comma-separated list of key-value pairs:
+
+```bash
+export OTEL_SPAN_ATTRIBUTES="team=backend,environment=production,version=1.2.3"
+```
+
+### Behavior
+
+- **Universal Application**: Attributes are added to ALL spans, including:
+  - Manually created spans (`tracer.start_span()`, `tracer.start_as_current_span()`)
+  - Lambda handler spans (`@lambda_handler`)
+  - AWS message handler spans (`@aws_message_handler`)
+  - Flask/FastAPI middleware spans
+  - Auto-instrumented spans (database queries, HTTP requests, etc.)
+
+- **Format**: Same as `OTEL_RESOURCE_ATTRIBUTES` - comma-separated `key=value` pairs
+- **Value Handling**: Supports values containing `=` characters (e.g., URLs)
+- **Whitespace**: Leading/trailing whitespace is automatically trimmed
+
+### Example
+
+```python
+import os
+
+# Set environment variable
+os.environ['OTEL_SPAN_ATTRIBUTES'] = "team=backend,service.owner=platform-team,deployment.region=us-east-1"
+
+# Initialize SDK
+from rebrandly_otel import otel, logger
+
+# Create any span - attributes are added automatically
+with otel.span('my-operation'):
+    logger.info('Processing request')
+    # The span will include:
+    # - team: "backend"
+    # - service.owner: "platform-team"
+    # - deployment.region: "us-east-1"
+    # ... plus any other attributes you set manually
+```
+
+### Use Cases
+
+- **Team/Ownership Tagging**: `team=backend,owner=john@example.com`
+- **Environment Metadata**: `environment=production,region=us-east-1,availability_zone=us-east-1a`
+- **Version Tracking**: `version=1.2.3,build=12345,commit=abc123def`
+- **Cost Attribution**: `cost_center=engineering,project=customer-api`
+- **Multi-Tenancy**: `tenant=acme-corp,customer_tier=enterprise`
+
+### Difference from OTEL_RESOURCE_ATTRIBUTES
+
+- **OTEL_RESOURCE_ATTRIBUTES**: Service-level metadata (set once, applies to the entire service instance)
+- **OTEL_SPAN_ATTRIBUTES**: Span-level metadata (added to each individual span at creation time)
+
+Both use the same format but serve different purposes in the OpenTelemetry data model.
+
 ### Exception Handling
 
 Spans automatically capture exceptions with:
@@ -521,6 +584,7 @@ pytest tests/test_usage.py -v
 pytest tests/test_pymysql_instrumentation.py -v
 pytest tests/test_metrics_and_logs.py -v
 pytest tests/test_decorators.py -v
+pytest tests/test_span_attributes_processor.py -v
 ```
 
 Run with coverage:
@@ -537,6 +601,7 @@ The test suite includes:
 - **PyMySQL instrumentation tests** (`test_pymysql_instrumentation.py`): Database connection instrumentation, query tracing, helper functions
 - **Metrics and logs tests** (`test_metrics_and_logs.py`): Custom metrics creation (counter, histogram, gauge), logging levels (info, warning, debug, error)
 - **Decorators tests** (`test_decorators.py`): Lambda handler decorator, AWS message handler decorator, traces decorator, aws_message_span context manager
+- **Span attributes processor tests** (`test_span_attributes_processor.py`): Automatic span attributes from OTEL_SPAN_ATTRIBUTES (31 tests)
 
 ## License
 

{rebrandly_otel-0.2.16.dist-info → rebrandly_otel-0.2.19.dist-info}/RECORD

@@ -7,9 +7,10 @@ rebrandly_otel/metrics.py,sha256=jZPygTY7vie33sadXc7P1DwLTKe9tJvAWSZuGHW1xQg,774
 rebrandly_otel/otel_utils.py,sha256=wbtr2_eZTRHmgqo6PY6nCe81zdyQXo9bpDd9D2NehrM,6028
 rebrandly_otel/pymysql_instrumentation.py,sha256=lS_V5DcsnpQ3f2PoNqeM7t3Jyiew2KNURM9iILfz8sM,6477
 rebrandly_otel/rebrandly_otel.py,sha256=8EArZTkeqV0IWLrgKH4vZzY-6VhJBNRp4_c99mpjJNw,22785
-rebrandly_otel/traces.py,sha256=JY_3RWbzpUxzEx3GqTVgggsyA2DB4oR-zDftIFFJha4,7174
-rebrandly_otel-0.2.16.dist-info/licenses/LICENSE,sha256=KMXHvTwP62S2q-SG7CFfMU_09rUwxiqlM0izaYGdcgY,1103
-rebrandly_otel-0.2.16.dist-info/METADATA,sha256=S-VxIpWMXW_ijcQj5v6RfiqVBYqCB71DbGbzptneGvI,15741
-rebrandly_otel-0.2.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-rebrandly_otel-0.2.16.dist-info/top_level.txt,sha256=26PSC1gjVUl8tTH5QfKbFevjVV4E2yojoukEfiTScvM,15
-rebrandly_otel-0.2.16.dist-info/RECORD,,
+rebrandly_otel/span_attributes_processor.py,sha256=eB5oeHwNw4gtD3opQYOJVOq7VQYRj2YEv4oL7BV0t9Q,3609
+rebrandly_otel/traces.py,sha256=Y7WE17vGYvetoxzjUBmAEnwI9r7GBMFffBww4zcnFbk,7402
+rebrandly_otel-0.2.19.dist-info/licenses/LICENSE,sha256=KMXHvTwP62S2q-SG7CFfMU_09rUwxiqlM0izaYGdcgY,1103
+rebrandly_otel-0.2.19.dist-info/METADATA,sha256=D5OUsMGWasrFLV0DhH5LDDQNTYyv1vsIz_d_cZUifKo,18807
+rebrandly_otel-0.2.19.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+rebrandly_otel-0.2.19.dist-info/top_level.txt,sha256=26PSC1gjVUl8tTH5QfKbFevjVV4E2yojoukEfiTScvM,15
+rebrandly_otel-0.2.19.dist-info/RECORD,,