From 2ce1b5b9621c59749aa6cef97b05ffac2b09460b Mon Sep 17 00:00:00 2001 From: Jonas Kunz Date: Thu, 7 Nov 2024 15:19:29 +0100 Subject: [PATCH] Fix readme --- inferred-spans/README.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/inferred-spans/README.md b/inferred-spans/README.md index 4af769e68..56ae21a5b 100644 --- a/inferred-spans/README.md +++ b/inferred-spans/README.md @@ -27,20 +27,21 @@ This extension supports [autoconfiguration](https://github.com/open-telemetry/op So if you are using an autoconfigured OpenTelemetry SDK, you'll only need to add this extension to your class path and configure it via system properties or environment variables: -| Property Name / Environment Variable Name | Default | Description | -|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| otel.inferred.spans.enabled
OTEL_INFERRED_SPANS_ENABLED | `false` | Enables the inferred spans feature. | -| otel.inferred.spans.logging.enabled
OTEL_INFERRED_SPANS_LOGGING_ENABLED | `true` | By default, async profiler prints warning messages about missing JVM symbols to standard output. Set this option to `true` to suppress such messages | -| otel.inferred.spans.backup.diagnostic.files
OTEL_INFERRED_SPANS_BACKUP_DIAGNOSTIC_FILES | `false` | Do not delete the temporary profiling files, can be used later to reproduce in case of issues. | -| otel.inferred.spans.safe.mode
OTEL_INFERRED_SPANS_SAFE_MODE | `0` | Can be used for analysis: the Async Profiler's area that deals with recovering stack trace frames is known to be sensitive in some systems. It is used as a bit mask using values are between 0 and 31, where 0 enables all recovery attempts and 31 disables all five (corresponding 1, 2, 4, 8 and 16). | -| otel.inferred.spans.post.processing.enabled
OTEL_INFERRED_SPANS_POST_PROCESSING_ENABLED | `true` | Can be used to test the effect of the async-profiler in isolation from the agent's post-processing. | -| otel.inferred.spans.sampling.interval
OTEL_INFERRED_SPANS_SAMPLING_INTERVAL | `50ms` | he frequency at which stack traces are gathered within a profiling session. The lower you set it, the more accurate the durations will be. This comes at the expense of higher overhead and more spans for potentially irrelevant operations. The minimal duration of a profiling-inferred span is the same as the value of this setting. | -| otel.inferred.spans.min.duration
OTEL_INFERRED_SPANS_MIN_DURATION | `0ms` | The minimum duration of an inferred span. Note that the min duration is also implicitly set by the sampling interval. However, increasing the sampling interval also decreases the accuracy of the duration of inferred spans. | -| otel.inferred.spans.included.classes
OTEL_INFERRED_SPANS_INCLUDED_CLASSES | `*` | If set, the agent will only create inferred spans for methods which match this list. Setting a value may slightly reduce overhead and can reduce clutter by only creating spans for the classes you are interested in.
Example: `org.example.myapp.*` | -| otel.inferred.spans.excluded.classes
OTEL_INFERRED_SPANS_EXCLUDED_CLASSES | `java.*`
`javax.*`
`sun.*`
`com.sun.*`
`jdk.*`
`org.apache.tomcat.*`
`org.apache.catalina.*`
`org.apache.coyote.*`
`org.jboss.as.*`
`org.glassfish.*`
`org.eclipse.jetty.*`
`com.ibm.websphere.*`
`io.undertow.*` | Excludes classes for which no profiler-inferred spans should be created. | -| otel.inferred.spans.interval
OTEL_INFERRED_SPANS_INTERVAL | `5s` | The interval at which profiling sessions should be started. | -| otel.inferred.spans.duration
OTEL_INFERRED_SPANS_DURATION | `5s` | The duration of a profiling session. For sampled transactions which fall within a profiling session (they start after and end before the session), so-called inferred spans will be created. They appear in the trace waterfall view like regular spans.
NOTE: It is not recommended to set much higher durations as it may fill the activation events file and async-profiler's frame buffer. Warnings will be logged if the activation events file is full. If you want to have more profiling coverage, try decreasing `profiling_inferred_spans_interval` | -| otel.inferred.spans.lib.directory
OTEL_INFERRED_SPANS_LIB_DIRECTORY | Defaults to the value of `java.io.tmpdir` | Profiling requires that the [async-profiler](https://github.com/async-profiler/async-profiler) shared library is exported to a temporary location and loaded by the JVM. The partition backing this location must be executable, however in some server-hardened environments, `noexec` may be set on the standard `/tmp` partition, leading to `java.lang.UnsatisfiedLinkError` errors. Set this property to an alternative directory (e.g. `/var/tmp`) to resolve this.
| otel.inferred.spans.duration
OTEL_INFERRED_SPANS_DURATION | `5s` | The duration of a profiling session. For sampled transactions which fall within a profiling session (they start after and end before the session), so-called inferred spans will be created. They appear in the trace waterfall view like regular spans.
NOTE: It is not recommended to set much higher durations as it may fill the activation events file and async-profiler's frame buffer. Warnings will be logged if the activation events file is full. If you want to have more profiling coverage, try decreasing `profiling_inferred_spans_interval` | +| Property Name / Environment Variable Name | Default | Description | +|-----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| otel.inferred.spans.enabled
OTEL_INFERRED_SPANS_ENABLED | `false` | Enables the inferred spans feature. | +| otel.inferred.spans.logging.enabled
OTEL_INFERRED_SPANS_LOGGING_ENABLED | `true` | By default, async profiler prints warning messages about missing JVM symbols to standard output. Set this option to `true` to suppress such messages | +| otel.inferred.spans.backup.diagnostic.files
OTEL_INFERRED_SPANS_BACKUP_DIAGNOSTIC_FILES | `false` | Do not delete the temporary profiling files, can be used later to reproduce in case of issues. | +| otel.inferred.spans.safe.mode
OTEL_INFERRED_SPANS_SAFE_MODE | `0` | Can be used for analysis: the Async Profiler's area that deals with recovering stack trace frames is known to be sensitive in some systems. It is used as a bit mask using values are between 0 and 31, where 0 enables all recovery attempts and 31 disables all five (corresponding 1, 2, 4, 8 and 16). | +| otel.inferred.spans.post.processing.enabled
OTEL_INFERRED_SPANS_POST_PROCESSING_ENABLED | `true` | Can be used to test the effect of the async-profiler in isolation from the agent's post-processing. | +| otel.inferred.spans.sampling.interval
OTEL_INFERRED_SPANS_SAMPLING_INTERVAL | `50ms` | he frequency at which stack traces are gathered within a profiling session. The lower you set it, the more accurate the durations will be. This comes at the expense of higher overhead and more spans for potentially irrelevant operations. The minimal duration of a profiling-inferred span is the same as the value of this setting. | +| otel.inferred.spans.min.duration
OTEL_INFERRED_SPANS_MIN_DURATION | `0ms` | The minimum duration of an inferred span. Note that the min duration is also implicitly set by the sampling interval. However, increasing the sampling interval also decreases the accuracy of the duration of inferred spans. | +| otel.inferred.spans.included.classes
OTEL_INFERRED_SPANS_INCLUDED_CLASSES | `*` | If set, the agent will only create inferred spans for methods which match this list. Setting a value may slightly reduce overhead and can reduce clutter by only creating spans for the classes you are interested in.
Example: `org.example.myapp.*` | +| otel.inferred.spans.excluded.classes
OTEL_INFERRED_SPANS_EXCLUDED_CLASSES | `java.*`
`javax.*`
`sun.*`
`com.sun.*`
`jdk.*`
`org.apache.tomcat.*`
`org.apache.catalina.*`
`org.apache.coyote.*`
`org.jboss.as.*`
`org.glassfish.*`
`org.eclipse.jetty.*`
`com.ibm.websphere.*`
`io.undertow.*` | Excludes classes for which no profiler-inferred spans should be created. | +| otel.inferred.spans.interval
OTEL_INFERRED_SPANS_INTERVAL | `5s` | The interval at which profiling sessions should be started. | +| otel.inferred.spans.duration
OTEL_INFERRED_SPANS_DURATION | `5s` | The duration of a profiling session. For sampled transactions which fall within a profiling session (they start after and end before the session), so-called inferred spans will be created. They appear in the trace waterfall view like regular spans.
NOTE: It is not recommended to set much higher durations as it may fill the activation events file and async-profiler's frame buffer. Warnings will be logged if the activation events file is full. If you want to have more profiling coverage, try decreasing `profiling_inferred_spans_interval` | +| otel.inferred.spans.lib.directory
OTEL_INFERRED_SPANS_LIB_DIRECTORY | Defaults to the value of `java.io.tmpdir` | Profiling requires that the [async-profiler](https://github.com/async-profiler/async-profiler) shared library is exported to a temporary location and loaded by the JVM. The partition backing this location must be executable, however in some server-hardened environments, `noexec` may be set on the standard `/tmp` partition, leading to `java.lang.UnsatisfiedLinkError` errors. Set this property to an alternative directory (e.g. `/var/tmp`) to resolve this. | +| otel.inferred.spans.duration
OTEL_INFERRED_SPANS_DURATION | `5s` | The duration of a profiling session. For sampled transactions which fall within a profiling session (they start after and end before the session), so-called inferred spans will be created. They appear in the trace waterfall view like regular spans.
NOTE: It is not recommended to set much higher durations as it may fill the activation events file and async-profiler's frame buffer. Warnings will be logged if the activation events file is full. If you want to have more profiling coverage, try decreasing `profiling_inferred_spans_interval` | | otel.inferred.spans.parent.override.handler
OTEL_INFERRED_SPANS_PARENT_OVERRIDE_HANDLER | Defaults to a handler adding span-links to the inferred span | Inferred spans sometimes need to be inserted as the new parent of a normal span, which is not directly possible because that span has already been sent. For this reason, this relationship needs to be represented differently, which normally is done by adding a span-link to the inferred span. This configuration can be used to override that behaviour by providing the fully qualified name of a class implementing `BiConsumer`: The biconsumer will be invoked with the inferred span as first argument and the span for which the inferred one was detected as new parent as second argument | ### Manual SDK setup