Move java sdk configuration documentation into docs site #4377
Conversation
|
@open-telemetry/java-instrumentation-maintainers PTAL |
@chalin I looked around for a pattern to follow for footnotes to ensure consistency and landed on mirroring the |
|
@open-telemetry/java-approvers @open-telemetry/java-instrumentation-approvers PTAL! |
|
Hi @jaydeluca - I've edited the opening comment to indicate that this PR contributes to #4032. We should only close #4032 once the corresponding pieces are removed from that file (I don't know if the entire file is covered here and will therefore be removed, or have a link added to this page). WDYT? |
There was a problem hiding this comment.
I'm on board with this, but would like to see us describe these env vars in a way that makes it clear that they can be used outside the otel java agent. I'd also like to see us bring everything over so we can delete https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md and have a single source of truth.
@jkwatson WDYT? If merged, we'll need to make sure we add notes to the contributors guide to indicate that any new env vars / system properties need to be updated here.
…nfigs into single entries, other format updates and review comments
…metry.io into move-java-config-docs
There was a problem hiding this comment.
I know these were just copy / pasted from the java directory, but seeing them prompted me to review and leave a few comments. I think all the comments are important, but don't necessarily need to be addressed in this PR. I'll defer to the maintainers on if they have any preference of fixing now or in a followup.
| For example `otel.instrumentation.common.default-enabled` would convert to | ||
| `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`. |
There was a problem hiding this comment.
Let's use a concrete example from below here:
| For example `otel.instrumentation.common.default-enabled` would convert to | |
| `OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED`. | |
| For example `otel.sdk.enabled` would convert to | |
| `OTEL_SDK_ENABLED`. |
|
|
||
| ## General | ||
|
|
||
| The autoconfigure module registers Java shutdown hooks to shut down the SDK when |
There was a problem hiding this comment.
Let's link to or provide some context on what the autoconfigure module actually is. We have to assume the reader doesn't know what the autoconfigure module is when they land on this page. Maybe a link to this: http://localhost:1313/docs/languages/java/instrumentation/#automatic-configuration
And that section should probably link back to this page for a full list of all options.
| Signal specific configurations take priority over the generic versions. | ||
|
|
||
| For example, if you set both `otel.exporter.otlp.endpoint` and | ||
| `otel.exporter.otlp.traces.endpoint`, the latter will take precedence. |
There was a problem hiding this comment.
Should we just include this text about priority inside the "Signal configuration" alert?
|
|
||
| Exporters which adhere to | ||
| `otel.java.experimental.exporter.memory_mode=reusable_data` are | ||
| `OtlpGrpcMetricExporter`, `OtlpHttpMetricExporter`, and `PrometheusHttpServer`. |
There was a problem hiding this comment.
| `OtlpGrpcMetricExporter`, `OtlpHttpMetricExporter`, and `PrometheusHttpServer`. | |
| `OtlpGrpc{Signal}Exporter`, `OtlpHttp{Signal}Exporter`, and `PrometheusHttpServer`. |
All the OTLP exporters now adhere to it.
|
|
||
| [^2]: | ||
|
|
||
| OpenTelemetry Java agent 2.x uses `http/protobuf` by default. |
There was a problem hiding this comment.
I think something is funky with the footnote display. When I run locally, clicking on the 2 footnote brings me to the bottom of the page.
| The policy has the following configuration, which there is currently no way to | ||
| customize: |
There was a problem hiding this comment.
| The policy has the following configuration, which there is currently no way to | |
| customize: | |
| The policy has the following configuration, which is can only be customized via programmatic configuration (see [customizing the OpenTelemetry SDK](#customizing-the-opentelemetry-sdk)): |
| You almost always want to specify the | ||
| [`service.name`](/docs/specs/semconv/resource/#service) for your application. It | ||
| corresponds to how you describe the application, for example `authservice` could | ||
| be an application that authenticates requests. If not specified, SDK defaults | ||
| the service name to `unknown_service:java`. |
There was a problem hiding this comment.
| You almost always want to specify the | |
| [`service.name`](/docs/specs/semconv/resource/#service) for your application. It | |
| corresponds to how you describe the application, for example `authservice` could | |
| be an application that authenticates requests. If not specified, SDK defaults | |
| the service name to `unknown_service:java`. | |
| You almost always want to specify `otel.service.name` to set the [`service.name`](/docs/specs/semconv/resource/#service) resource attribute, which represents the logical name of your service. If not specified, the SDK sets `service.name=unknown_service:java` by default. |
| If you are using the `ResourceProvider` SPI, which many instrumentation agent | ||
| distributions include automatically, you can turn on or off one or more of them | ||
| by using the following configuration items: |
There was a problem hiding this comment.
| If you are using the `ResourceProvider` SPI, which many instrumentation agent | |
| distributions include automatically, you can turn on or off one or more of them | |
| by using the following configuration items: | |
| Many instrumentation agent distributions automatically various `ResourceProvider` implementations. These can be turned on or off as follows: |
|
|
||
| Supported values are the following: | ||
|
|
||
| | Value | Description | |
There was a problem hiding this comment.
Can we add a column to this table with the artifact that contains each of these?
tracecontextlives inopentelemetry-apibaggagelives inopentelemetry-apib3lives inopentelemetry-extension-trace-propagatorsb3multilives inopentelemetry-extension-trace-propagatorsjaegerlives inopentelemetry-extension-trace-propagatorsxraylives inio.opentelemetry.contrib:opentelemetry-aws-xray-propagatorottracelives inopentelemetry-extension-trace-propagators
| `OtlpGrpcMetricExporter`, `OtlpHttpMetricExporter`, and `PrometheusHttpServer`. | ||
| Support for additional exporters may be added in the future. | ||
|
|
||
| #### OTLP exporter (span, metric, and log exporters) |
There was a problem hiding this comment.
We should mention the artifact coordinates in each place where we describe configuration that requires a particular artifact to be included in order to work.
I think this comes up for each of the exporter sections (otlp, logging, logging-otlp, zipkin, prometheus), and for the propagators.
👍 sounds good, thanks for all the feedback and ideas. i'm happy to address them now or in a followup based on the preference of the maintainers |
cartermp
removed
the
sig-approval-missing
|
@jaydeluca if you can file a follow-up issue here to cover some of what @jack-berg mentioned, that'd be great! |
Contributes to:
java/automatic/configurationlinks out to pages that should be moved to docs #4032Notes:
Preview: https://deploy-preview-4377--opentelemetry.netlify.app/docs/languages/java/automatic/configuration/#resources