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]: Zero-code CLI Instrumentation for LLM and AI Agents (#850)

Patcher00955e70f5c0
diff --git a/docs/latest/sdk-configuration.mdx b/docs/latest/sdk-configuration.mdx
index b9eb0873..290512c5 100644
--- a/docs/latest/sdk-configuration.mdx
+++ b/docs/latest/sdk-configuration.mdx
@@ -7,25 +7,35 @@ icon: 'file-code'
<Tabs>
<Tab title="Python">
-## Observability - `openlit.init()`
+## Observability - `openlit.init()` | `openlit-instrument`
Below is a detailed overview of the configuration options available, allowing you to adjust OpenLIT's behavior and functionality to align with your specific observability needs:
-
-| Argument | Description | Default Value | Required |
-|-------------------------|-----------------------------------------------------------------------------------------------|----------------|----------|
-| `environment` | The deployment environment of the application. | `"default"` | Yes |
-| `application_name` | Identifies the name of your application. | `"default"` | Yes |
-| `tracer` | An instance of OpenTelemetry Tracer for tracing operations. | `None` | No |
-| `meter` | An OpenTelemetry Metrics instance for capturing metrics. | `None` | No |
-| `otlp_endpoint` | Specifies the OTLP endpoint for transmitting telemetry data. | `None` | No |
-| `otlp_headers` | Defines headers for the OTLP exporter, useful for backends requiring authentication. | `None` | No |
-| `disable_batch` | A flag to disable batch span processing, favoring immediate dispatch. | `False` | No |
-| `capture_message_content` | Enables tracing of content for deeper insights. | `True` | No |
-| `disabled_instrumentors`| List of instrumentors to disable. | `None` | No |
-| `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 |
+| Parameter | CLI Argument | Environment Variable | Description | Default | Required |
+|-----------|--------------|---------------------|-------------|---------|----------|
+| `environment` | `--environment` | `OTEL_DEPLOYMENT_ENVIRONMENT` | Deployment environment | `"default"` | No |
+| `service_name` | `--service_name` | `OTEL_SERVICE_NAME` | Service name for tracing | `"default"` | No |
+| `otlp_endpoint` | `--otlp_endpoint` | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint for exporter | `None` | No |
+| `otlp_headers` | `--otlp_headers` | `OTEL_EXPORTER_OTLP_HEADERS` | OTLP headers as JSON string | `None` | No |
+| `disable_batch` | `--disable_batch` | `OPENLIT_DISABLE_BATCH` | Disable batch span processing | `False` | No |
+| `capture_message_content` | `--capture_message_content` | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Enable capture of message content | `True` | No |
+| `disabled_instrumentors` | `--disabled_instrumentors` | `OPENLIT_DISABLED_INSTRUMENTORS` | Comma-separated list of instrumentors to disable | `None` | No |
+| `disable_metrics` | `--disable_metrics` | `OPENLIT_DISABLE_METRICS` | Disable metrics collection | `False` | No |
+| `pricing_json` | `--pricing_json` | `OPENLIT_PRICING_JSON` | File path or URL to pricing JSON | `None` | No |
+| `detailed_tracing` | `--detailed_tracing` | `OPENLIT_DETAILED_TRACING` | Enable detailed component-level tracing | `True` | No |
+| `collect_system_metrics` | `--collect_system_metrics` | `OPENLIT_COLLECT_SYSTEM_METRICS` | Enable comprehensive system metrics (CPU, memory, disk, network, GPU if detected) | `False` | No |
+| `tracer` | N/A | N/A | An instance of OpenTelemetry Tracer for tracing operations | `None` | No |
+| `event_logger` | N/A | N/A | EventLoggerProvider instance | `None` | No |
+| `meter` | N/A | N/A | OpenTelemetry Metrics instance | `None` | No |
+
+### Deprecated Parameters
+
+| Parameter | CLI Argument | Environment Variable | Description | Default | Required |
+|-----------|--------------|---------------------|-------------|---------|----------|
+| `application_name` | `--application_name` | `OTEL_SERVICE_NAME` | Application name for tracing (**deprecated**, use `service_name`) | `"default"` | No |
+| `collect_gpu_stats` | `--collect_gpu_stats` | `OPENLIT_COLLECT_GPU_STATS` | Enable GPU statistics collection (**deprecated**, use `collect_system_metrics`) | `False` | No |
+
+**Note:** Environment variables take precedence over CLI arguments, which take precedence over function parameters.
## Prompt Hub - `openlit.get_prompt()`
diff --git a/sdk/python/pyproject.toml b/sdk/python/pyproject.toml
index e58c9dec..4ed360f9 100644
--- a/sdk/python/pyproject.toml
+++ b/sdk/python/pyproject.toml
@@ -1,6 +1,6 @@
[tool.poetry]
name = "openlit"
-version = "1.34.43"
+version = "1.35.0"
description = "OpenTelemetry-native Auto instrumentation library for monitoring LLM Applications and GPUs, facilitating the integration of observability into your GenAI-driven projects"
authors = ["OpenLIT"]
license = "Apache-2.0"
@@ -21,11 +21,31 @@ opentelemetry-api = "^1.30.0"
opentelemetry-sdk = "^1.30.0"
opentelemetry-exporter-otlp = "^1.30.0"
opentelemetry-instrumentation = ">=0.52b0,<1.0.0"
+# Official OpenTelemetry HTTP Framework instrumentations
+opentelemetry-instrumentation-asgi = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-django = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-fastapi = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-flask = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-pyramid = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-starlette = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-falcon = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-tornado = ">=0.52b0,<1.0.0"
+# Official OpenTelemetry HTTP Client instrumentations
+opentelemetry-instrumentation-aiohttp-client = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-httpx = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-requests = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-urllib = ">=0.52b0,<1.0.0"
+opentelemetry-instrumentation-urllib3 = ">=0.52b0,<1.0.0"
+# Official OpenTelemetry System Metrics (optional)
+opentelemetry-instrumentation-system-metrics = {version = ">=0.52b0,<1.0.0", optional = true}
openai = "^1.1.1"
anthropic = ">=0.42.0,<1.0.0"
openai-agents = ">=0.0.3"
langchain = "^0.3.15"
+[tool.poetry.scripts]
+openlit-instrument = "openlit.cli.main:run"
+
[build-system]
requires = ["poetry-core>=1.1.0"]
build-backend = "poetry.core.masonry.api"
diff --git a/sdk/python/src/openlit/__init__.py b/sdk/python/src/openlit/__init__.py
index 7085e718..c8fde6b6 100644
--- a/sdk/python/src/openlit/__init__.py
+++ b/sdk/python/src/openlit/__init__.py
@@ -137,6 +137,26 @@ def module_exists(module_name):
return True
+def is_opentelemetry_instrumentor(instrumentor_name):
+ """Check if the instrumentor is an official OpenTelemetry instrumentor."""
+ opentelemetry_instrumentors = {
+ "asgi",
+ "django",
+ "fastapi",
+ "flask",
+ "pyramid",
+ "starlette",
+ "falcon",
+ "tornado",
+ "aiohttp-client",
+ "httpx",
+ "requests",
+ "urllib",
+ "urllib3",
+ }
+ return instrumentor_name in opentelemetry_instrumentors
+
+
def instrument_if_available(
instrumentor_name, instrumentor_instance, config, disabled_instrumentors
):
@@ -152,17 +172,23 @@ def instrument_if_available(
try:
if module_exists(module_name):
- instrumentor_instance.instrument(
- environment=config.environment,
- application_name=config.application_name,
- tracer=config.tracer,
- event_provider=config.event_provider,
- pricing_info=config.pricing_info,
- capture_message_content=config.capture_message_content,
- metrics_dict=config.metrics_dict,
- disable_metrics=config.disable_metrics,
- detailed_tracing=config.detailed_tracing,
- )
+ if is_opentelemetry_instrumentor(instrumentor_name):
+ # OpenTelemetry instrumentations use the standard instrument() method
+ instrumentor_instance.instrument()
+ logger.info("OpenTelemetry instrumentor %s enabled", instrumentor_name)
+ else:
+ # OpenLIT custom instrumentations use extended parameters
+ instrumentor_instance.instrument(
+ environment=config.environment,
+ application_name=config.application_name,
+ tracer=config.tracer,
+ event_provider=config.event_provider,
+ pricing_info=config.pricing_info,
+ capture_message_content=config.capture_message_content,
+ metrics_dict=config.metrics_dict,
+ disable_metrics=config.disable_metrics,
+ detailed_tracing=config.detailed_tracing,
+ )
else:
logger.info(
"Library for %s (%s) not found. Skipping instrumentation",
@@ -176,6 +202,7 @@ def instrument_if_available(
def init(
environment="default",
application_name="default",
+ service_name="default",
tracer=None,
event_logger=None,
otlp_endpoint=None,
@@ -188,6 +215,7 @@ def init(
pricing_json=None,
collect_gpu_stats=False,
detailed_tracing=True,
+ collect_system_metrics=False,
):
"""
Initializes the openLIT configuration and setups tracing.
@@ -215,6 +243,59 @@ def init(
disabled_instrumentors = disabled_instrumentors if disabled_instrumentors else []
logger.info("Starting openLIT initialization...")
+ # Handle service_name/application_name migration
+ # service_name takes precedence over application_name if both are provided
+ if service_name != "default":
+ # service_name explicitly provided, use it
+ final_service_name = service_name
+ elif application_name != "default":
+ # Only application_name provided, use it (silent for backward compatibility)
+ final_service_name = application_name
+ else:
+ # Both are default, will be handled by environment variables below
+ final_service_name = "default"
+
+ # Apply environment variables for parameters not explicitly provided
+ # Environment variables take precedence over default values but not over explicit parameters
+ try:
+ from openlit.cli.config import build_config_from_environment
+
+ env_config = build_config_from_environment()
+
+ # Apply env vars only if function parameters are at their default values
+ if environment == "default" and "environment" in env_config:
+ environment = env_config["environment"]
+
+ # Handle service name from environment (both service_name and application_name map to same env var)
+ if final_service_name == "default":
+ final_service_name = env_config.get(
+ "service_name",
+ env_config.get(
+ "application_name", "default"
+ ), # Fallback for backward compatibility
+ )
+ # Skip otlp_endpoint and otlp_headers - let existing code handle them
+ if disable_batch is False and "disable_batch" in env_config:
+ disable_batch = env_config["disable_batch"]
+ if capture_message_content is True and "capture_message_content" in env_config:
+ capture_message_content = env_config["capture_message_content"]
+ if not disabled_instrumentors and "disabled_instrumentors" in env_config:
+ disabled_instrumentors = env_config["disabled_instrumentors"]
+ if disable_metrics is False and "disable_metrics" in env_config:
+ disable_metrics = env_config["disable_metrics"]
+ if pricing_json is None and "pricing_json" in env_config:
+ pricing_json = env_config["pricing_json"]
+ if collect_gpu_stats is False and "collect_gpu_stats" in env_config:
+ collect_gpu_stats = env_config["collect_gpu_stats"]
+ if detailed_tracing is True and "detailed_tracing" in env_config:
+ detailed_tracing = env_config["detailed_tracing"]
+ if collect_system_metrics is False and "collect_system_metrics" in env_config:
+ collect_system_metrics = env_config["collect_system_metrics"]
+
+ except ImportError:
+ # Fallback if config module is not available - continue without env var support
+ pass
+
# Validate disabled instrumentors
invalid_instrumentors = [
name for name in disabled_instrumentors if name not in MODULE_NAME_MAP
@@ -230,7 +311,7 @@ def init(
# Setup tracing based on the provided or default configuration.
tracer = setup_tracing(
- application_name=application_name,
+ application_name=final_service_name,
environment=environment,
tracer=tracer,
otlp_endpoint=otlp_endpoint,
@@ -244,7 +325,7 @@ def init(
# Setup events based on the provided or default configuration.
event_provider = setup_events(
- application_name=application_name,
+ application_name=final_service_name,
environment=environment,
event_logger=event_logger,
otlp_endpoint=None,
@@ -257,7 +338,7 @@ def init(
# Setup meter and receive metrics_dict instead of meter.
metrics_dict, err = setup_meter(
- application_name=application_name,
+ application_name=final_service_name,
environment=environment,
meter=meter,
otlp_endpoint=otlp_endpoint,
@@ -281,7 +362,7 @@ def init(
# Update global configuration with the provided settings.
config.update_config(
environment,
- application_name,
+ final_service_name,
tracer,
event_provider,
otlp_endpoint,
@@ -301,12 +382,41 @@ def init(
for name, instrumentor in instrumentor_instances.items():
instrument_if_available(name, instrumentor, config, disabled_instrumentors)
- # Handle GPU instrumentation separately
+ # Handle GPU instrumentation separately (only if GPU is found)
if not disable_metrics and collect_gpu_stats:
- GPUInstrumentor().instrument(
- environment=config.environment,
- application_name=config.application_name,
- )
+ gpu_instrumentor = GPUInstrumentor()
+ if gpu_instrumentor._get_gpu_type(): # Only instrument if GPU is detected
+ gpu_instrumentor.instrument(
+ environment=config.environment,
+ application_name=config.application_name,
+ )
+ else:
+ logger.info("No GPU detected, skipping GPU metrics collection")
+
+ # Handle OpenTelemetry System Metrics instrumentation
+ if not disable_metrics and collect_system_metrics:
+ try:
+ from opentelemetry.instrumentation.system_metrics import (
+ SystemMetricsInstrumentor,
+ )
+
+ SystemMetricsInstrumentor().instrument()
+
+ # Auto-enable GPU metrics if GPU is detected (comprehensive system monitoring)
+ gpu_instrumentor = GPUInstrumentor()
+ if gpu_instrumentor._get_gpu_type():
+ gpu_instrumentor.instrument(
+ environment=config.environment,
+ application_name=config.application_name,
+ )
+
+ except ImportError:
+ logger.warning(
+ "OpenTelemetry system metrics not available. "
+ "Install with: pip install opentelemetry-instrumentation-system-metrics"
+ )
+ except Exception as e:
+ logger.error("Failed to enable system metrics: %s", e)
except Exception as e:
logger.error("Error during openLIT initialization: %s", e)
diff --git a/sdk/python/src/openlit/_instrumentors.py b/sdk/python/src/openlit/_instrumentors.py
index 5913d762..8e0ed46a 100644
--- a/sdk/python/src/openlit/_instrumentors.py
+++ b/sdk/python/src/openlit/_instrumentors.py
@@ -6,6 +6,7 @@ import importlib
# Mapping of instrumentor names to their required Python packages
MODULE_NAME_MAP = {
+ # OpenLIT AI/ML instrumentations
"openai": "openai",
"anthropic": "anthropic",
"cohere": "cohere",
@@ -52,10 +53,26 @@ MODULE_NAME_MAP = {
"pydantic_ai": "pydantic_ai",
"sarvam": "sarvamai",
"browser-use": "browser_use",
+ # Official OpenTelemetry HTTP Framework instrumentations
+ "asgi": "asgiref",
+ "django": "django",
+ "fastapi": "fastapi",
+ "flask": "flask",
+ "pyramid": "pyramid",
+ "starlette": "starlette",
+ "falcon": "falcon",
+ "tornado": "tornado",
+ # Official OpenTelemetry HTTP Client instrumentations
+ "aiohttp-client": "aiohttp",
+ "httpx": "httpx",
+ "requests": "requests",
+ "urllib": "urllib",
+ "urllib3": "urllib3",
}
# Dictionary mapping instrumentor names to their full module paths
INSTRUMENTOR_MAP = {
+ # OpenLIT AI/ML instrumentations
"openai": "openlit.instrumentation.openai.OpenAIInstrumentor",
"anthropic": "openlit.instrumentation.anthropic.AnthropicInstrumentor",
"cohere": "openlit.instrumentation.cohere.CohereInstrumentor",
@@ -102,6 +119,21 @@ INSTRUMENTOR_MAP = {
"pydantic_ai": "openlit.instrumentation.pydantic_ai.PydanticAIInstrumentor",
"sarvam": "openlit.instrumentation.sarvam.SarvamInstrumentor",
"browser-use": "openlit.instrumentation.browser_use.BrowserUseInstrumentor",
+ # Official OpenTelemetry HTTP Framework instrumentations
+ "asgi": "opentelemetry.instrumentation.asgi.AsgiInstrumentor",
+ "django": "opentelemetry.instrumentation.django.DjangoInstrumentor",
+ "fastapi": "opentelemetry.instrumentation.fastapi.FastAPIInstrumentor",
+ "flask": "opentelemetry.instrumentation.flask.FlaskInstrumentor",
+ "pyramid": "opentelemetry.instrumentation.pyramid.PyramidInstrumentor",
+ "starlette": "opentelemetry.instrumentation.starlette.StarletteInstrumentor",
+ "falcon": "opentelemetry.instrumentation.falcon.FalconInstrumentor",
+ "tornado": "opentelemetry.instrumentation.tornado.TornadoInstrumentor",
+ # Official OpenTelemetry HTTP Client instrumentations
+ "aiohttp-client": "opentelemetry.instrumentation.aiohttp_client.AioHttpClientInstrumentor",
+ "httpx": "opentelemetry.instrumentation.httpx.HTTPXClientInstrumentor",
+ "requests": "opentelemetry.instrumentation.requests.RequestsInstrumentor",
+ "urllib": "opentelemetry.instrumentation.urllib.URLLibInstrumentor",
+ "urllib3": "opentelemetry.instrumentation.urllib3.URLLib3Instrumentor",
}
diff --git a/sdk/python/src/openlit/cli/__init__.py b/sdk/python/src/openlit/cli/__init__.py
new file mode 100644
index 00000000..1636938f
--- /dev/null
+++ b/sdk/python/src/openlit/cli/__init__.py
@@ -0,0 +1,14 @@
+"""
+OpenLIT CLI
+
+This module provides CLI-based auto-instrumentation functionality similar to
+OpenTelemetry's approach, allowing users to instrument their applications
+without code changes using the existing OpenLIT instrumentations.
+
+All openlit.init() parameters can be set via CLI arguments or environment variables.
+CLI arguments take precedence over environment variables.
+"""
+
+from .main import run
+
+__all__ = ["run"]
diff --git a/sdk/python/src/openlit/cli/bootstrap/sitecustomize.py b/sdk/python/src/openlit/cli/bootstrap/sitecustomize.py
new file mode 100644
index 00000000..bf09d03b
--- /dev/null
+++ b/sdk/python/src/openlit/cli/bootstrap/sitecustomize.py
@@ -0,0 +1,116 @@
+"""
+OpenLIT Auto-Initialization Bootstrap
+
+This module automatically initializes OpenLIT when Python starts
+if OPENLIT_AUTO_INSTRUMENT environment variable is set.
+
+This follows the same pattern as OpenTelemetry's auto-instrumentation.
+"""
+
+import os
+import logging
+
+# Import the centralized configuration
+try:
+ # First try absolute import
+ from openlit.cli.config import build_config_from_environment
+except ImportError:
+ try:
+ # Try relative import as fallback
+ from ..config import build_config_from_environment
+ except ImportError:
+ # Final fallback - build config manually from environment
+ def build_config_from_environment():
+ """Build configuration from environment variables as fallback."""
+
+ config = {}
+
+ # Map environment variables to OpenLIT parameters
+ env_mappings = {
+ "OTEL_SERVICE_NAME": "application_name",
+ "OTEL_DEPLOYMENT_ENVIRONMENT": "environment",
+ "OTEL_EXPORTER_OTLP_ENDPOINT": "otlp_endpoint",
+ "OTEL_EXPORTER_OTLP_HEADERS": "otlp_headers",
+ "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT": "capture_message_content",
+ "OPENLIT_DISABLED_INSTRUMENTORS": "disabled_instrumentors",
+ "OPENLIT_DISABLE_BATCH": "disable_batch",
+ "OPENLIT_DISABLE_METRICS": "disable_metrics",
+ "OPENLIT_COLLECT_GPU_STATS": "collect_gpu_stats",
+ "OPENLIT_DETAILED_TRACING": "detailed_tracing",
+ "OPENLIT_PRICING_JSON": "pricing_json",
+ }
+
+ for env_var, param_name in env_mappings.items():
+ if env_value := os.environ.get(env_var):
+ # Handle boolean values
+ if env_var in [
+ "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT",
+ "OPENLIT_DISABLE_BATCH",
+ "OPENLIT_DISABLE_METRICS",
+ "OPENLIT_COLLECT_GPU_STATS",
+ "OPENLIT_DETAILED_TRACING",
+ ]:
+ config[param_name] = env_value.lower() in ("true", "1", "yes")
+ # Handle CSV values
+ elif env_var == "OPENLIT_DISABLED_INSTRUMENTORS":
+ config[param_name] = [
+ item.strip()
+ for item in env_value.split(",")
+ if item.strip()
+ ]
+ # Handle JSON values
+ elif env_var == "OTEL_EXPORTER_OTLP_HEADERS":
+ try:
+ import json
+
+ config[param_name] = json.loads(env_value)
+ except (json.JSONDecodeError, ImportError):
+ pass
+ else:
+ config[param_name] = env_value
+
+ return config
+
+
+# Set up logging for auto-instrumentation
+logger = logging.getLogger(__name__)
+
+
+def initialize(*, swallow_exceptions: bool = True) -> None:
+ """
+ Setup auto-instrumentation, called by the sitecustomize module
+
+ :param swallow_exceptions: Whether or not to propagate instrumentation exceptions to the caller.
+ Exceptions are logged and swallowed by default.
+ """
+ # Prevents auto-instrumentation of subprocesses if code execs another python process
+ if "PYTHONPATH" in os.environ:
+ current_dir = os.path.dirname(os.path.abspath(__file__))
+ python_path = os.environ["PYTHONPATH"].split(os.pathsep)
+ # Remove current directory from PYTHONPATH to prevent subprocess instrumentation
+ python_path = [path for path in python_path if path != current_dir]
+ os.environ["PYTHONPATH"] = os.pathsep.join(python_path)
+
+ try:
+ # Import OpenLIT and initialize
+ import openlit
+
+ # Build configuration from environment variables
+ config = build_config_from_environment()
+
+ # Initialize OpenLIT with environment variables
+ openlit.init(**config)
+
+ except ImportError as e:
+ if not swallow_exceptions:
+ raise
+ logger.error("OpenLIT not found. Please ensure openlit is installed: %s", e)
+ except Exception as e:
+ if not swallow_exceptions:
+ raise
+ # Log error but don't break the application
+ logger.error("OpenLIT auto-instrumentation failed: %s", e)
+
+
+# Auto-initialize when module is imported (like OpenTelemetry does)
+initialize()
diff --git a/sdk/python/src/openlit/cli/config.py b/sdk/python/src/openlit/cli/config.py
new file mode 100644
index 00000000..42fb1998
--- /dev/null
+++ b/sdk/python/src/openlit/cli/config.py
@@ -0,0 +1,170 @@
+"""
+Centralized configuration for OpenLIT CLI
+
+This module defines all openlit.init() parameters and their corresponding
+CLI arguments and environment variables in one place to ensure consistency.
+"""
+
+import logging
+import os
+from typing import Dict, Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+# Centralized parameter configuration - SINGLE SOURCE OF TRUTH
+# Add new parameters here ONLY - they will automatically appear in both CLI and openlit.init()
+PARAMETER_CONFIG = {
+ "environment": {
+ "default": "default",
+ "env_var": "OTEL_DEPLOYMENT_ENVIRONMENT",
+ "cli_help": "Deployment environment",
+ "cli_type": str,
+ },
+ "application_name": {
+ "default": "default",
+ "env_var": "OTEL_SERVICE_NAME",
+ "cli_help": "Application name for tracing (deprecated, use service_name)",
+ "cli_type": str,
+ "deprecated": True, # Mark as deprecated for future removal
+ },
+ "service_name": {
+ "default": "default",
+ "env_var": "OTEL_SERVICE_NAME", # Same env var as application_name
+ "cli_help": "Service name for tracing",
+ "cli_type": str,
+ },
+ "otlp_endpoint": {
+ "default": None,
+ "env_var": "OTEL_EXPORTER_OTLP_ENDPOINT",
+ "cli_help": "OTLP endpoint for exporter",
+ "cli_type": str,
+ },
+ "otlp_headers": {
+ "default": None,
+ "env_var": "OTEL_EXPORTER_OTLP_HEADERS",
+ "cli_help": "OTLP headers as JSON string",
+ "cli_type": str,
+ "parser": "json", # Special handling needed
+ },
+ "disable_batch": {
+ "default": False,
+ "env_var": "OPENLIT_DISABLE_BATCH",
+ "cli_help": "Disable batch span processing",
+ "cli_type": bool,
+ },
+ "capture_message_content": {
+ "default": True,
+ "env_var": "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT",
+ "cli_help": "Enable capture of message content",
+ "cli_type": bool,
+ "has_negation": True, # Supports --no_capture_message_content
+ },
+ "disabled_instrumentors": {
+ "default": None,
+ "env_var": "OPENLIT_DISABLED_INSTRUMENTORS",
+ "cli_help": "Comma-separated list of instrumentors to disable",
+ "cli_type": str,
+ "parser": "csv", # Special handling needed
+ },
+ "disable_metrics": {
+ "default": False,
+ "env_var": "OPENLIT_DISABLE_METRICS",
+ "cli_help": "Disable metrics collection",
+ "cli_type": bool,
+ },
+ "pricing_json": {
+ "default": None,
+ "env_var": "OPENLIT_PRICING_JSON",
+ "cli_help": "File path or URL to pricing JSON",
+ "cli_type": str,
+ },
+ "collect_gpu_stats": {
+ "default": False,
+ "env_var": "OPENLIT_COLLECT_GPU_STATS",
+ "cli_help": "Enable GPU statistics collection",
+ "cli_type": bool,
+ },
+ "detailed_tracing": {
+ "default": True,
+ "env_var": "OPENLIT_DETAILED_TRACING",
+ "cli_help": "Enable detailed component-level tracing",
+ "cli_type": bool,
+ "has_negation": True, # Supports --no_detailed_tracing
+ },
+ "collect_system_metrics": {
+ "default": False,
+ "env_var": "OPENLIT_COLLECT_SYSTEM_METRICS",
+ "cli_help": "Enable comprehensive system metrics (CPU, memory, disk, network, GPU if detected)",
+ "cli_type": bool,
+ },
+ # Parameters that are not exposed via CLI (internal use only)
+ "tracer": {
+ "default": None,
+ "internal": True, # Skip in CLI
+ },
+ "event_logger": {
+ "default": None,
+ "internal": True, # Skip in CLI
+ },
+ "meter": {
+ "default": None,
+ "internal": True, # Skip in CLI
+ },
+}
+
+
+def get_cli_parameters() -> Dict[str, Dict[str, Any]]:
+ """Get parameters that should be exposed in the CLI."""
+ return {
+ name: config
+ for name, config in PARAMETER_CONFIG.items()
+ if not config.get("internal", False)
+ }
+
+
+def get_env_var_for_parameter(param_name: str) -> Optional[str]:
+ """Get the environment variable name for a given parameter."""
+ config = PARAMETER_CONFIG.get(param_name, {})
+ return config.get("env_var")
+
+
+def parse_env_value(param_name: str, env_value: str) -> Any:
+ """Parse environment variable value based on parameter configuration."""
+ config = PARAMETER_CONFIG.get(param_name, {})
+ parser = config.get("parser")
+ cli_type = config.get("cli_type", str)
+
+ if cli_type == bool:
+ return env_value.lower() in {"true", "1", "yes"}
+ elif parser == "json":
+ try:
+ import json
+
+ return json.loads(env_value)
+ except (json.JSONDecodeError, ImportError):
+ return None
+ elif parser == "csv":
+ return [item.strip() for item in env_value.split(",") if item.strip()]
+ else:
+ return env_value
+
+
+def build_config_from_environment() -> Dict[str, Any]:
+ """Build OpenLIT configuration from environment variables."""
+ config = {}
+
+ for param_name, param_config in PARAMETER_CONFIG.items():
+ if param_config.get("internal", False):
+ continue
+
+ env_var = param_config.get("env_var")
+ if not env_var:
+ continue
+
+ if env_value := os.environ.get(env_var):
+ parsed_value = parse_env_value(param_name, env_value)
+ if parsed_value is not None:
+ config[param_name] = parsed_value
+
+ return config
diff --git a/sdk/python/src/openlit/cli/main.py b/sdk/python/src/openlit/cli/main.py
new file mode 100644
index 00000000..7fe1fa4e
--- /dev/null
+++ b/sdk/python/src/openlit/cli/main.py
@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+OpenLIT Auto-Instrumentation CLI
+
+This module provides a CLI tool for auto-instrumenting Python applications
+with OpenLIT observability without requiring code changes.
+
+Usage:
+ openlit-instrument --application_name myapp --otlp_endpoint https://cloud.openlit.io python app.py
+"""
+
+import os
+import sys
+import argparse
+import logging
+from shutil import which
+
+from openlit.cli.config import get_cli_parameters
+
+logger = logging.getLogger(__name__)
+
+
+def parse_arguments() -> tuple:
+ """Parse command line arguments and return parsed args and target command."""
+ # Build environment variables help text
+ env_vars_help = []
+ cli_params = get_cli_parameters()
+ for param_name, config in cli_params.items():
+ env_var = config.get("env_var", "")
+ help_text = config.get("cli_help", "")
+ env_vars_help.append(f" {env_var:<50} {help_text}")
+
+ parser = argparse.ArgumentParser(
+ prog="openlit-instrument",
+ description="Auto-instrument Python applications with OpenLIT observability",
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ epilog=f"""
+Examples:
+ # Using CLI arguments
+ openlit-instrument --service-name myapp --deployment-environment production python app.py
+
+ # Using environment variables (takes precedence over CLI args)
+ OTEL_SERVICE_NAME=myapp OTEL_DEPLOYMENT_ENVIRONMENT=production openlit-instrument python app.py
+
+ # Mixed usage
+ openlit-instrument --otlp-endpoint https://cloud.openlit.io python app.py
+
+ # Disable specific instrumentations
+ openlit-instrument --disabled-instrumentors chromadb,pinecone python main.py
+
+Environment Variables (take precedence over CLI arguments):
+ Configure OpenLIT using these environment variables:
+{chr(10).join(env_vars_help)}
+ """,
+ )
+
+ # Dynamically add CLI arguments from PARAMETER_CONFIG
+ cli_params = get_cli_parameters()
+ for param_name, config in cli_params.items():
+ cli_arg = f"--{param_name}" # Use underscores like function parameters
+ cli_help = (
+ f"{config.get('cli_help', '')} (equivalent to {config.get('env_var', '')})"
+ )
+ cli_type = config.get("cli_type", str)
+
+ if cli_type == bool:
+ parser.add_argument(cli_arg, action="store_true", help=cli_help)
+ else:
+ parser.add_argument(cli_arg, help=cli_help)
+
+ parser.add_argument("--version", action="version", version="%(prog)s 1.0.0")
+
+ # Use OpenTelemetry's approach: command and command_args with REMAINDER
+ parser.add_argument("command", help="Your Python application.")
+ parser.add_argument(
+ "command_args",
+ help="Arguments for your application.",
+ nargs=argparse.REMAINDER,
+ )
+
+ args = parser.parse_args()
+
+ # Reconstruct target command from OpenTelemetry's format
+ target_command = [args.command] + args.command_args
+
+ return args, target_command
+
+
+def set_environment_from_cli_args(args) -> None:
+ """Set environment variables from CLI arguments (only if env vars are not already set)."""
+ # Dynamically map CLI arguments to environment variables from PARAMETER_CONFIG
+ cli_params = get_cli_parameters()
+
+ for param_name, config in cli_params.items():
+ env_var = config.get("env_var")
+ if not env_var:
+ continue
+
+ # Only set if environment variable is not already set (env vars take precedence)
+ if env_var not in os.environ:
+ cli_value = getattr(args, param_name, None)
+ if cli_value is not None:
+ # Handle boolean values
+ if isinstance(cli_value, bool):
+ os.environ[env_var] = "true" if cli_value else "false"
+ else:
+ os.environ[env_var] = str(cli_value)
+
+
+def setup_python_path() -> None:
+ """Setup PYTHONPATH exactly like OpenTelemetry does."""
+ python_path = os.environ.get("PYTHONPATH")
+
+ python_path = [] if not python_path else python_path.split(os.pathsep)
+ # Add current working directory (like OpenTelemetry does)
+ cwd_path = os.getcwd()
+ if cwd_path not in python_path:
+ python_path.insert(0, cwd_path)
+
+ # Add bootstrap directory path
+ current_dir = os.path.dirname(os.path.abspath(__file__))
+ bootstrap_path = os.path.join(current_dir, "bootstrap")
+
+ # Ensure the directory exists
+ os.makedirs(bootstrap_path, exist_ok=True)
+
+ # Remove bootstrap path if it exists, then add at beginning
+ python_path = [path for path in python_path if path != bootstrap_path]
+ python_path.insert(0, bootstrap_path)
+
+ os.environ["PYTHONPATH"] = os.pathsep.join(python_path)
+
+
+def run() -> None:
+ """Main entry point for openlit-instrument CLI."""
+ try:
+ # Parse CLI arguments and target command
+ args, target_command = parse_arguments()
+
+ # Set environment variables from CLI arguments (env vars take precedence)
+ set_environment_from_cli_args(args)
+
+ # Setup Python path for auto-initialization
+ setup_python_path()
+
+ # Execute target application using OpenTelemetry's approach
+ executable = which(target_command[0])
+ if not executable:
+ logger.warning(
+ "Command not found: %s. Attempting direct execution as fallback.",
+ target_command[0],
+ )
+ # Fallback: try to execute directly (user's PATH might have it)
+ try:
+ os.execvpe(target_command[0], target_command, os.environ)
+ except (FileNotFoundError, OSError) as e:
+ logger.error("Failed to execute command %s: %s", target_command[0], e)
+ logger.error(
+ "OpenLIT instrumentation failed, but this should not break your application"
+ )
+ return
+ else:
+ os.execl(executable, executable, *target_command[1:])
+
+ except KeyboardInterrupt:
+ # Only acceptable exit - user explicitly interrupted
+ sys.exit(130)
+ except Exception as e:
+ logger.error("OpenLIT CLI failed: %s", e)
+ logger.error(
+ "This should not prevent your application from running. Consider running without openlit-instrument."
+ )
+ # Don't exit - let the process continue
+
+
+if __name__ == "__main__":
+ run()