Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

feat: add custom_metrics_attributes for grouping metrics by custom tags (#1115)

Dheeraj Bhaskaruni0a7f1a42d376
diff --git a/docs/latest/sdk/configuration.mdx b/docs/latest/sdk/configuration.mdx
index d9173e10..a157a962 100644
--- a/docs/latest/sdk/configuration.mdx
+++ b/docs/latest/sdk/configuration.mdx
@@ -47,6 +47,7 @@ Customize OpenLIT SDK behavior for your specific instrumentation needs:
| `pricing_json` | `--pricing_json` | `OPENLIT_PRICING_JSON` | Custom pricing configuration for accurate LLM cost tracking | `None` | No |
| `disable_events` | `--disable_events` | `OPENLIT_DISABLE_EVENTS` | Disable OTel Logger event emission | `False` | No |
| `collect_system_metrics` | `--collect_system_metrics` | `OPENLIT_COLLECT_SYSTEM_METRICS` | Comprehensive system monitoring (CPU, memory, disk, network, GPU) for AI workloads | `False` | No |
+| `custom_metrics_attributes` | N/A | N/A | Custom key-value attributes applied to every metric recording. Useful for grouping metrics by custom tags (e.g., client ID, team, project). Reserved keys like `service.name` cannot be overwritten. | `None` | No |
### Database instrumentation options
diff --git a/sdk/python/README.md b/sdk/python/README.md
index 670a22be..1aa58a24 100644
--- a/sdk/python/README.md
+++ b/sdk/python/README.md
@@ -192,6 +192,7 @@ Below is a detailed overview of the configuration options available, allowing yo
| `disable_metrics` | If set, disables the collection of metrics. | `False` | No |
| `pricing_json` | URL or file path of the pricing JSON file. | `https://github.com/openlit/openlit/blob/main/assets/pricing.json` | No |
| `collect_gpu_stats` | Flag to enable or disable GPU metrics collection. | `False` | No |
+| `custom_metrics_attributes` | Custom key-value attributes applied to every metric recording. Useful for grouping metrics by custom tags (e.g., client ID, team, project). | `None` | No |
### OpenLIT Prompt Hub - `openlit.get_prompt()`
diff --git a/sdk/python/src/openlit/__helpers.py b/sdk/python/src/openlit/__helpers.py
index 93a1cd27..18957347 100644
--- a/sdk/python/src/openlit/__helpers.py
+++ b/sdk/python/src/openlit/__helpers.py
@@ -459,9 +459,28 @@ def create_metrics_attributes(
if error_type:
attributes[SemanticConvention.ERROR_TYPE] = error_type
+ _apply_custom_metrics_attributes(attributes)
+
return attributes
+def _apply_custom_metrics_attributes(attributes: Dict[Any, Any]) -> None:
+ """
+ Merges user-defined custom_metrics_attributes from OpenlitConfig into the
+ given attributes dict. Custom attributes cannot overwrite reserved core
+ keys (service.name, telemetry.sdk.name, deployment.environment) to prevent
+ accidental corruption of standard OTel resource attributes.
+ """
+ config = OpenlitConfig()
+ if not config.custom_metrics_attributes:
+ return
+
+ reserved_keys = {TELEMETRY_SDK_NAME, SERVICE_NAME, DEPLOYMENT_ENVIRONMENT}
+ for key, value in config.custom_metrics_attributes.items():
+ if key not in reserved_keys:
+ attributes[key] = value
+
+
def create_db_metrics_attributes(
service_name: str,
deployment_environment: str,
@@ -474,7 +493,7 @@ def create_db_metrics_attributes(
Returns OTel metrics attributes for database operations
"""
- return {
+ attributes = {
TELEMETRY_SDK_NAME: "openlit",
SERVICE_NAME: service_name,
DEPLOYMENT_ENVIRONMENT: deployment_environment,
@@ -484,6 +503,10 @@ def create_db_metrics_attributes(
SemanticConvention.SERVER_PORT: server_port,
}
+ _apply_custom_metrics_attributes(attributes)
+
+ return attributes
+
def set_server_address_and_port(
client_instance: Any, default_server_address: str, default_server_port: int
diff --git a/sdk/python/src/openlit/__init__.py b/sdk/python/src/openlit/__init__.py
index 611cdc24..02f4e756 100644
--- a/sdk/python/src/openlit/__init__.py
+++ b/sdk/python/src/openlit/__init__.py
@@ -136,6 +136,7 @@ def init(
evals_logs_export=True,
max_content_length=None,
custom_span_attributes=None,
+ custom_metrics_attributes=None,
):
"""
Initializes the openLIT configuration and setups tracing.
@@ -169,6 +170,10 @@ def init(
custom_span_attributes (dict): Custom key-value attributes applied to every auto-instrumented
span. Values must be valid OTel attribute types (str, int,
float, bool, or sequences thereof). Optional.
+ custom_metrics_attributes (dict): Custom key-value attributes applied to every metric
+ recording. Useful for grouping metrics by custom tags
+ (e.g., client ID, team, project). Values must be valid
+ OTel attribute types. Optional.
"""
disabled_instrumentors = normalize_instrumentor_names(disabled_instrumentors)
logger.info("Starting openLIT initialization...")
@@ -327,6 +332,7 @@ def init(
evals_logs_export,
max_content_length,
custom_span_attributes,
+ custom_metrics_attributes,
)
# Create instrumentor instances dynamically
diff --git a/sdk/python/src/openlit/_config.py b/sdk/python/src/openlit/_config.py
index 55529ef2..7b39e4ce 100644
--- a/sdk/python/src/openlit/_config.py
+++ b/sdk/python/src/openlit/_config.py
@@ -50,6 +50,7 @@ class OpenlitConfig:
cls.evals_logs_export = True
cls.max_content_length = None # None = no truncation
cls.custom_span_attributes = {}
+ cls.custom_metrics_attributes = {}
@classmethod
def update_config(
@@ -68,6 +69,7 @@ class OpenlitConfig:
evals_logs_export=True,
max_content_length=None,
custom_span_attributes=None,
+ custom_metrics_attributes=None,
):
"""
Updates the configuration based on provided parameters.
@@ -87,6 +89,7 @@ class OpenlitConfig:
evals_logs_export (bool): Emit evaluation results as OTEL Log Records instead of OTEL Events.
max_content_length: Maximum character length for captured content (None = no limit).
custom_span_attributes (dict): Custom key-value attributes applied to every span.
+ custom_metrics_attributes (dict): Custom key-value attributes applied to every metric.
"""
cls.environment = environment
cls.application_name = application_name
@@ -102,3 +105,4 @@ class OpenlitConfig:
cls.evals_logs_export = evals_logs_export
cls.max_content_length = max_content_length
cls.custom_span_attributes = custom_span_attributes or {}
+ cls.custom_metrics_attributes = custom_metrics_attributes or {}
diff --git a/sdk/python/src/openlit/cli/config.py b/sdk/python/src/openlit/cli/config.py
index 5a02dce3..48d9f768 100644
--- a/sdk/python/src/openlit/cli/config.py
+++ b/sdk/python/src/openlit/cli/config.py
@@ -122,6 +122,13 @@ PARAMETER_CONFIG = {
"cli_type": str,
"parser": "json",
},
+ "custom_metrics_attributes": {
+ "default": None,
+ "env_var": "OPENLIT_CUSTOM_METRICS_ATTRIBUTES",
+ "cli_help": 'Custom metrics attributes as JSON string (e.g. \'{"team": "ml"}\')',
+ "cli_type": str,
+ "parser": "json",
+ },
}