From 11df7e3683fd127e489dae0c4bb33743124c4611 Mon Sep 17 00:00:00 2001 From: sginji Date: Sun, 27 Jul 2025 09:53:33 -0700 Subject: [PATCH 1/5] Update docs for entrypoints --- docs/sdk/entry_points.rst | 77 +++++++++++++++++++++++++++++++++++++++ docs/sdk/index.rst | 1 + 2 files changed, 78 insertions(+) create mode 100644 docs/sdk/entry_points.rst diff --git a/docs/sdk/entry_points.rst b/docs/sdk/entry_points.rst new file mode 100644 index 00000000000..48f606a3008 --- /dev/null +++ b/docs/sdk/entry_points.rst @@ -0,0 +1,77 @@ +Entry Points +============ + +OpenTelemetry Python uses Python's **entry points** mechanism to provide a pluggable architecture. Entry points allow you to register custom components (exporters, samplers, etc.) that can be discovered and loaded at runtime. + +Configuration +------------- + +Entry points are controlled via environment variables: + +* ``OTEL_TRACES_EXPORTER`` - Trace exporters (e.g., ``console``, ``otlp_proto_grpc``) +* ``OTEL_METRICS_EXPORTER`` - Metrics exporters (e.g., ``console``, ``prometheus``) +* ``OTEL_LOGS_EXPORTER`` - Log exporters (e.g., ``console``, ``otlp_proto_http``) +* ``OTEL_TRACES_SAMPLER`` - Trace samplers (e.g., ``always_on``, ``traceidratio``) +* ``OTEL_PROPAGATORS`` - Context propagators (e.g., ``tracecontext,baggage``) + +Available Entry Point Groups +---------------------------- + +**Exporters** - Send telemetry data to backends: + +* ``opentelemetry_traces_exporter`` - Trace exporters +* ``opentelemetry_metrics_exporter`` - Metrics exporters +* ``opentelemetry_logs_exporter`` - Log exporters + +**Configuration** - Control telemetry behavior: + +* ``opentelemetry_traces_sampler`` - Decide which traces to collect +* ``opentelemetry_id_generator`` - Generate trace/span IDs +* ``opentelemetry_resource_detector`` - Detect environment info + +**Context** - Manage distributed tracing context: + +* ``opentelemetry_propagator`` - Cross-service context propagation +* ``opentelemetry_context`` - Context storage mechanism + +**Providers** - Core telemetry factories: + +* ``opentelemetry_tracer_provider`` - Create tracers +* ``opentelemetry_meter_provider`` - Create meters +* ``opentelemetry_logger_provider`` - Create loggers + +Creating a Custom Exporter +--------------------------- + +1. **Create your exporter class**: + +.. code-block:: python + + from opentelemetry.sdk.trace.export import SpanExporter + + class MyExporter(SpanExporter): + def export(self, spans): + # Your export logic here + for span in spans: + print(f"Exporting: {span.name}") + +2. **Register in pyproject.toml**: + +.. code-block:: toml + + [project.entry-points.opentelemetry_traces_exporter] + my_exporter = "mypackage.exporters:MyExporter" + +3. **Use it**: + +.. code-block:: bash + + export OTEL_TRACES_EXPORTER=my_exporter + python your_app.py + +See Also +-------- + +* :doc:`trace` - Trace SDK documentation +* :doc:`metrics` - Metrics SDK documentation +* :doc:`environment_variables` - Environment variable reference \ No newline at end of file diff --git a/docs/sdk/index.rst b/docs/sdk/index.rst index d5d3688443f..a9d4ff070f1 100644 --- a/docs/sdk/index.rst +++ b/docs/sdk/index.rst @@ -12,3 +12,4 @@ OpenTelemetry Python SDK metrics error_handler environment_variables + entry_points From 8613eea8050f21fe2e34870d1ab33b1d086eec32 Mon Sep 17 00:00:00 2001 From: sginji Date: Sun, 10 Aug 2025 00:12:14 -0700 Subject: [PATCH 2/5] Remove redundancy, add names with poss values --- docs/sdk/entry_points.rst | 125 +++++++++++++++++++------------------- 1 file changed, 62 insertions(+), 63 deletions(-) diff --git a/docs/sdk/entry_points.rst b/docs/sdk/entry_points.rst index 48f606a3008..db6747da114 100644 --- a/docs/sdk/entry_points.rst +++ b/docs/sdk/entry_points.rst @@ -1,73 +1,72 @@ Entry Points ============ -OpenTelemetry Python uses Python's **entry points** mechanism to provide a pluggable architecture. Entry points allow you to register custom components (exporters, samplers, etc.) that can be discovered and loaded at runtime. +OpenTelemetry Python uses Python's `entry points `_ mechanism to provide a pluggable architecture. Entry points allow you to register custom components (exporters, samplers, etc.) that can be discovered and loaded at runtime. Configuration ------------- -Entry points are controlled via environment variables: - -* ``OTEL_TRACES_EXPORTER`` - Trace exporters (e.g., ``console``, ``otlp_proto_grpc``) -* ``OTEL_METRICS_EXPORTER`` - Metrics exporters (e.g., ``console``, ``prometheus``) -* ``OTEL_LOGS_EXPORTER`` - Log exporters (e.g., ``console``, ``otlp_proto_http``) -* ``OTEL_TRACES_SAMPLER`` - Trace samplers (e.g., ``always_on``, ``traceidratio``) -* ``OTEL_PROPAGATORS`` - Context propagators (e.g., ``tracecontext,baggage``) - -Available Entry Point Groups ----------------------------- - -**Exporters** - Send telemetry data to backends: - -* ``opentelemetry_traces_exporter`` - Trace exporters -* ``opentelemetry_metrics_exporter`` - Metrics exporters -* ``opentelemetry_logs_exporter`` - Log exporters - -**Configuration** - Control telemetry behavior: - -* ``opentelemetry_traces_sampler`` - Decide which traces to collect -* ``opentelemetry_id_generator`` - Generate trace/span IDs -* ``opentelemetry_resource_detector`` - Detect environment info - -**Context** - Manage distributed tracing context: - -* ``opentelemetry_propagator`` - Cross-service context propagation -* ``opentelemetry_context`` - Context storage mechanism - -**Providers** - Core telemetry factories: - -* ``opentelemetry_tracer_provider`` - Create tracers -* ``opentelemetry_meter_provider`` - Create meters -* ``opentelemetry_logger_provider`` - Create loggers - -Creating a Custom Exporter ---------------------------- - -1. **Create your exporter class**: - -.. code-block:: python - - from opentelemetry.sdk.trace.export import SpanExporter - - class MyExporter(SpanExporter): - def export(self, spans): - # Your export logic here - for span in spans: - print(f"Exporting: {span.name}") - -2. **Register in pyproject.toml**: - -.. code-block:: toml - - [project.entry-points.opentelemetry_traces_exporter] - my_exporter = "mypackage.exporters:MyExporter" - -3. **Use it**: - -.. code-block:: bash - - export OTEL_TRACES_EXPORTER=my_exporter - python your_app.py +The SDK supports configuring entry points via environment variables by specifying the entry point name. For a complete list of supported environment variables, see :doc:`../api/environment_variables`. + +Entry Point Configuration Reference +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + :widths: 20 20 40 20 + + * - Environment Variable + - Entry Point Group + - Available Entrypoint Names + - Base Type + * - OTEL_LOGS_EXPORTER + - opentelemetry_logs_exporter + - ``console``, ``otlp_proto_grpc``, ``otlp_proto_http`` + - LogExporter + * - OTEL_METRICS_EXPORTER + - opentelemetry_metrics_exporter + - ``console``, ``otlp``, ``otlp_proto_grpc``, + ``otlp_proto_http``, ``prometheus`` + - :class:`MetricExporter ` or :class:`MetricReader ` + * - OTEL_PROPAGATORS + - opentelemetry_propagator + - ``b3``, ``b3multi``, ``baggage``, + ``jaeger``, ``tracecontext`` + - :class:`TextMapPropagator ` + * - OTEL_TRACES_SAMPLER + - opentelemetry_traces_sampler + - ``always_off``, ``always_on``, ``parentbased_always_off``, + ``parentbased_always_on``, ``parentbased_traceidratio``, ``traceidratio`` + - :class:`Sampler ` + * - OTEL_EXPERIMENTAL_RESOURCE_DETECTORS + - opentelemetry_resource_detector + - ``host``, ``os``, ``otel``, ``process`` + - :class:`ResourceDetector ` + * - OTEL_PYTHON_ID_GENERATOR + - opentelemetry_id_generator + - ``random`` + - :class:`IdGenerator ` + * - OTEL_TRACES_EXPORTER + - opentelemetry_traces_exporter + - ``console``, ``otlp``, ``otlp_proto_grpc``, ``otlp_proto_http``, + ``zipkin``, ``zipkin_json``, ``zipkin_proto`` + - :class:`SpanExporter ` + * - OTEL_PYTHON_TRACER_PROVIDER + - opentelemetry_tracer_provider + - ``default_tracer_provider``, ``sdk_tracer_provider`` + - :class:`TracerProvider ` + * - OTEL_PYTHON_METER_PROVIDER + - opentelemetry_meter_provider + - ``default_meter_provider``, ``sdk_meter_provider`` + - :class:`MeterProvider ` + * - OTEL_PYTHON_LOGGER_PROVIDER + - opentelemetry_logger_provider + - ``default_logger_provider``, ``sdk_logger_provider`` + - :class:`LoggerProvider ` + * - OTEL_PYTHON_EVENT_LOGGER_PROVIDER + - opentelemetry_event_logger_provider + - ``default_event_logger_provider`` + - *No implementations available* See Also -------- From daf360db288ced3ab01d0e08c509511a796e2d55 Mon Sep 17 00:00:00 2001 From: sginji Date: Sat, 16 Aug 2025 13:20:18 -0700 Subject: [PATCH 3/5] Move entrypoint documentation to separate blocks --- docs/sdk/entry_points.rst | 135 ++++++++++++++++++++++---------------- 1 file changed, 79 insertions(+), 56 deletions(-) diff --git a/docs/sdk/entry_points.rst b/docs/sdk/entry_points.rst index db6747da114..61436912d2a 100644 --- a/docs/sdk/entry_points.rst +++ b/docs/sdk/entry_points.rst @@ -11,62 +11,85 @@ The SDK supports configuring entry points via environment variables by specifyin Entry Point Configuration Reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. list-table:: - :header-rows: 1 - :widths: 20 20 40 20 - - * - Environment Variable - - Entry Point Group - - Available Entrypoint Names - - Base Type - * - OTEL_LOGS_EXPORTER - - opentelemetry_logs_exporter - - ``console``, ``otlp_proto_grpc``, ``otlp_proto_http`` - - LogExporter - * - OTEL_METRICS_EXPORTER - - opentelemetry_metrics_exporter - - ``console``, ``otlp``, ``otlp_proto_grpc``, - ``otlp_proto_http``, ``prometheus`` - - :class:`MetricExporter ` or :class:`MetricReader ` - * - OTEL_PROPAGATORS - - opentelemetry_propagator - - ``b3``, ``b3multi``, ``baggage``, - ``jaeger``, ``tracecontext`` - - :class:`TextMapPropagator ` - * - OTEL_TRACES_SAMPLER - - opentelemetry_traces_sampler - - ``always_off``, ``always_on``, ``parentbased_always_off``, - ``parentbased_always_on``, ``parentbased_traceidratio``, ``traceidratio`` - - :class:`Sampler ` - * - OTEL_EXPERIMENTAL_RESOURCE_DETECTORS - - opentelemetry_resource_detector - - ``host``, ``os``, ``otel``, ``process`` - - :class:`ResourceDetector ` - * - OTEL_PYTHON_ID_GENERATOR - - opentelemetry_id_generator - - ``random`` - - :class:`IdGenerator ` - * - OTEL_TRACES_EXPORTER - - opentelemetry_traces_exporter - - ``console``, ``otlp``, ``otlp_proto_grpc``, ``otlp_proto_http``, - ``zipkin``, ``zipkin_json``, ``zipkin_proto`` - - :class:`SpanExporter ` - * - OTEL_PYTHON_TRACER_PROVIDER - - opentelemetry_tracer_provider - - ``default_tracer_provider``, ``sdk_tracer_provider`` - - :class:`TracerProvider ` - * - OTEL_PYTHON_METER_PROVIDER - - opentelemetry_meter_provider - - ``default_meter_provider``, ``sdk_meter_provider`` - - :class:`MeterProvider ` - * - OTEL_PYTHON_LOGGER_PROVIDER - - opentelemetry_logger_provider - - ``default_logger_provider``, ``sdk_logger_provider`` - - :class:`LoggerProvider ` - * - OTEL_PYTHON_EVENT_LOGGER_PROVIDER - - opentelemetry_event_logger_provider - - ``default_event_logger_provider`` - - *No implementations available* +**Logs Exporter** + +:Environment Variable: ``OTEL_LOGS_EXPORTER`` +:Entry Point Group: ``opentelemetry_logs_exporter`` +:Available Names: ``console``, ``otlp_proto_grpc``, ``otlp_proto_http`` +:Base Type: ``LogExporter`` *(alpha)* + +**Metrics Exporter** + +:Environment Variable: ``OTEL_METRICS_EXPORTER`` +:Entry Point Group: ``opentelemetry_metrics_exporter`` +:Available Names: ``console``, ``otlp``, ``otlp_proto_grpc``, ``otlp_proto_http``, ``prometheus`` +:Base Type: :class:`MetricExporter ` or :class:`MetricReader ` + +**Propagators** + +:Environment Variable: ``OTEL_PROPAGATORS`` +:Entry Point Group: ``opentelemetry_propagator`` +:Available Names: ``b3``, ``b3multi``, ``baggage``, ``jaeger``, ``tracecontext`` +:Base Type: :class:`TextMapPropagator ` + +**Traces Sampler** + +:Environment Variable: ``OTEL_TRACES_SAMPLER`` +:Entry Point Group: ``opentelemetry_traces_sampler`` +:Available Names: ``always_off``, ``always_on``, ``parentbased_always_off``, ``parentbased_always_on``, ``parentbased_traceidratio``, ``traceidratio`` +:Base Type: :class:`Sampler ` + +**Resource Detectors** + +:Environment Variable: ``OTEL_EXPERIMENTAL_RESOURCE_DETECTORS`` +:Entry Point Group: ``opentelemetry_resource_detector`` +:Available Names: ``host``, ``os``, ``otel``, ``process`` +:Base Type: :class:`ResourceDetector ` + +**ID Generator** + +:Environment Variable: ``OTEL_PYTHON_ID_GENERATOR`` +:Entry Point Group: ``opentelemetry_id_generator`` +:Available Names: ``random`` +:Base Type: :class:`IdGenerator ` + +**Traces Exporter** + +:Environment Variable: ``OTEL_TRACES_EXPORTER`` +:Entry Point Group: ``opentelemetry_traces_exporter`` +:Available Names: ``console``, ``otlp``, ``otlp_proto_grpc``, ``otlp_proto_http``, ``zipkin``, ``zipkin_json``, ``zipkin_proto`` +:Base Type: :class:`SpanExporter ` + +**Tracer Provider** + +:Environment Variable: ``OTEL_PYTHON_TRACER_PROVIDER`` +:Entry Point Group: ``opentelemetry_tracer_provider`` +:Available Names: ``default_tracer_provider``, ``sdk_tracer_provider`` +:Base Type: :class:`TracerProvider ` + +**Meter Provider** + +:Environment Variable: ``OTEL_PYTHON_METER_PROVIDER`` +:Entry Point Group: ``opentelemetry_meter_provider`` +:Available Names: ``default_meter_provider``, ``sdk_meter_provider`` +:Base Type: :class:`MeterProvider ` + +**Logger Provider** + +:Environment Variable: ``OTEL_PYTHON_LOGGER_PROVIDER`` +:Entry Point Group: ``opentelemetry_logger_provider`` +:Available Names: ``sdk_logger_provider`` +:Base Type: :class:`LoggerProvider ` + +**Event Logger Provider** + +:Environment Variable: ``OTEL_PYTHON_EVENT_LOGGER_PROVIDER`` +:Entry Point Group: ``opentelemetry_event_logger_provider`` *(not implemented)* +:Available Names: *None - no entry point implementations exist* +:Base Type: ``EventLoggerProvider`` *(experimental)* + +.. note:: + The Events API is `experimental `_ and currently has no entry point implementations. See Also -------- From 2c8f4b291ddc7c14835d586155df8effcaf8348c Mon Sep 17 00:00:00 2001 From: sginji Date: Sat, 16 Aug 2025 13:22:15 -0700 Subject: [PATCH 4/5] Indicate LogExporter is experimental --- docs/sdk/entry_points.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/entry_points.rst b/docs/sdk/entry_points.rst index 61436912d2a..445e6688b4e 100644 --- a/docs/sdk/entry_points.rst +++ b/docs/sdk/entry_points.rst @@ -16,7 +16,7 @@ Entry Point Configuration Reference :Environment Variable: ``OTEL_LOGS_EXPORTER`` :Entry Point Group: ``opentelemetry_logs_exporter`` :Available Names: ``console``, ``otlp_proto_grpc``, ``otlp_proto_http`` -:Base Type: ``LogExporter`` *(alpha)* +:Base Type: ``LogExporter`` *(experimental)* **Metrics Exporter** From d8792e1e630be0c0d8c38d6b31d9307c3a1fbad3 Mon Sep 17 00:00:00 2001 From: sginji Date: Mon, 18 Aug 2025 08:34:33 -0700 Subject: [PATCH 5/5] Update docs/sdk/entry_points.rst Co-authored-by: Riccardo Magliocchetti --- docs/sdk/entry_points.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sdk/entry_points.rst b/docs/sdk/entry_points.rst index 445e6688b4e..ae38e34103c 100644 --- a/docs/sdk/entry_points.rst +++ b/docs/sdk/entry_points.rst @@ -16,7 +16,7 @@ Entry Point Configuration Reference :Environment Variable: ``OTEL_LOGS_EXPORTER`` :Entry Point Group: ``opentelemetry_logs_exporter`` :Available Names: ``console``, ``otlp_proto_grpc``, ``otlp_proto_http`` -:Base Type: ``LogExporter`` *(experimental)* +:Base Type: ``LogExporter`` *(development)* **Metrics Exporter**