Update docs for entrypoints #4701
Conversation
docs/sdk/entry_points.rst
Outdated
| 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. |
There was a problem hiding this comment.
Can we link to the official entry point documentation here
docs/sdk/entry_points.rst
Outdated
| Configuration | ||
| ------------- | ||
|
|
||
| Entry points are controlled via environment variables: |
There was a problem hiding this comment.
Maybe -- the name (I think that is the official term from the entry points doc) of the entry point is set to environment variables
There was a problem hiding this comment.
I'm not sure I agree with the PR here, e.g. for -contrib this is not true. Entry points is what we use for providing extensibility without coupling the code (i.e. a plugin system) from different python packages and in practice they are a system we use to load code from a configuration. Then you can add that some options leverage entry points, as Dylan wrote, requiring to specify the entry point name in order to load some specific code.
There was a problem hiding this comment.
thanks! i've updated this - please lmk if this looks better
docs/sdk/entry_points.rst
Outdated
| Configuration | ||
| ------------- | ||
|
|
||
| Entry points are controlled via environment variables: |
There was a problem hiding this comment.
Can we link to something that lists all the environment variables
There was a problem hiding this comment.
Yes I think we could link the API environment variables doc (sourced here and here) instead of duplicating here in the SDK docs.
docs/sdk/entry_points.rst
Outdated
|
|
||
| Entry points are controlled via environment variables: | ||
|
|
||
| * ``OTEL_TRACES_EXPORTER`` - Trace exporters (e.g., ``console``, ``otlp_proto_grpc``) |
There was a problem hiding this comment.
Maybe we should have a 3 column table -- environment variables, entry point name, available options provided by otel python SDK/exporter package ?
There was a problem hiding this comment.
done and added a 4th column to link to the base class as mentioned in one of the other comments!
There was a problem hiding this comment.
Looks like there's not enough room for all four columns without hidden overflow. Another possibility would be to convert each row into its own block.
docs/sdk/entry_points.rst
Outdated
|
|
||
| **Exporters** - Send telemetry data to backends: | ||
|
|
||
| * ``opentelemetry_traces_exporter`` - Trace exporters |
There was a problem hiding this comment.
I think when the code loads it in it checks the type, it'd be good if we could link to the actual type here. Maybe the actual definition in the .py file is best?
docs/sdk/entry_points.rst
Outdated
|
|
||
| * ``opentelemetry_traces_sampler`` - Decide which traces to collect | ||
| * ``opentelemetry_id_generator`` - Generate trace/span IDs | ||
| * ``opentelemetry_resource_detector`` - Detect environment info |
There was a problem hiding this comment.
Again if possible can we link to the expected type? I appreciate the very brief explanation of what the thing is tho..
docs/sdk/entry_points.rst
Outdated
| * ``opentelemetry_meter_provider`` - Create meters | ||
| * ``opentelemetry_logger_provider`` - Create loggers | ||
|
|
||
| Creating a Custom Exporter |
There was a problem hiding this comment.
I think this section is useful. It would be good to put this information somewhere without duplicating what the API and SDK docs already describe (e.g. the env vars mentioned above). Alternative locations could be as a new example or as a special exporters topic. Or maybe in the otel.io docs.
| * - OTEL_LOGS_EXPORTER | ||
| - opentelemetry_logs_exporter | ||
| - ``console``, ``otlp_proto_grpc``, ``otlp_proto_http`` | ||
| - LogExporter |
There was a problem hiding this comment.
this is an _internal class - should it still be linked here? is it relevant still?
Description
Update docs with content about entrypoints and how they can they be setup
Fixes # issue
Type of change
Please delete options that are not relevant.
How Has This Been Tested?
Does This PR Require a Contrib Repo Change?
Checklist: