From 2d7395c44bf53d3e0cf3a8cc2cfbc97550114c0c Mon Sep 17 00:00:00 2001 From: Aaron Ai Date: Thu, 17 Nov 2022 12:48:42 +0800 Subject: [PATCH] Introduce markdown lint check (#7175) Fixes #7129 --- .github/workflows/build-daily.yml | 3 + .github/workflows/build-pull-request.yml | 6 + .github/workflows/build.yml | 5 + .../reusable-markdown-lint-check.yml | 17 ++ .markdownlint.yml | 14 ++ CONTRIBUTING.md | 26 +-- VERSIONING.md | 6 +- benchmark-overhead/README.md | 7 +- docs/contributing/debugging.md | 8 +- .../intellij-setup-and-troubleshooting.md | 2 +- docs/contributing/muzzle.md | 4 + docs/contributing/repository-settings.md | 2 +- docs/contributing/using-instrumenter-api.md | 2 +- .../writing-instrumentation-module.md | 4 + docs/contributing/writing-instrumentation.md | 1 + docs/java-7-rationale.md | 16 +- docs/logger-mdc-instrumentation.md | 1 + docs/misc/inter-thread-context-propagation.md | 6 + docs/misc/interop-design/interop-design.md | 14 +- docs/scope.md | 2 +- docs/semantic-conventions.md | 1 - docs/supported-libraries.md | 10 +- examples/distro/README.md | 11 +- examples/extension/README.md | 4 + .../apache-dbcp-2.0/library/README.md | 2 +- .../aws-lambda-core-1.0/library/README.md | 10 +- .../aws-lambda-events-2.2/library/README.md | 10 +- instrumentation/c3p0-0.9/library/README.md | 2 +- .../external-annotations/README.md | 6 +- .../graphql-java-12.0/library/README.md | 2 +- instrumentation/grpc-1.6/library/README.md | 2 +- .../hikaricp-3.0/library/README.md | 2 +- instrumentation/jdbc/library/README.md | 14 +- instrumentation/jetty/README.md | 1 + .../jmx-metrics/javaagent/README.md | 36 ++-- .../kafka-clients-2.6/library/README.md | 2 +- instrumentation/kotlinx-coroutines/README.md | 4 +- .../ktor/ktor-1.0/library/README.md | 2 +- .../ktor/ktor-2.0/library/README.md | 2 +- .../log4j-appender-2.17/library/README.md | 2 +- .../library-autoconfigure/README.md | 2 +- .../logback-appender-1.0/library/README.md | 2 +- .../logback/logback-mdc-1.0/library/README.md | 4 +- instrumentation/methods/README.md | 4 +- .../okhttp/okhttp-3.0/library/README.md | 2 +- .../README.md | 4 +- .../README.md | 4 +- .../oracle-ucp-11.2/library/README.md | 2 +- instrumentation/resources/library/README.md | 15 +- .../rocketmq-client-4.8/library/README.md | 2 +- .../runtime-metrics/library/README.md | 2 +- instrumentation/servlet/README.md | 10 +- instrumentation/spring/README.md | 160 +++++++++--------- .../spring-boot-autoconfigure/README.md | 14 +- .../spring/spring-web-3.1/library/README.md | 2 +- .../spring-webflux-5.0/library/README.md | 2 +- .../spring-webmvc-5.3/library/README.md | 5 +- .../jaeger-spring-boot-starter/README.md | 4 +- .../starters/spring-boot-starter/README.md | 5 +- .../zipkin-spring-boot-starter/README.md | 4 +- instrumentation/tomcat/README.md | 1 + .../vibur-dbcp-11.0/library/README.md | 2 +- smoke-tests/README.md | 1 + smoke-tests/images/play/README.md | 1 + smoke-tests/images/servlet/README.md | 1 + smoke-tests/images/spring-boot/README.md | 1 + testing-common/src/misc/README.md | 6 +- 67 files changed, 319 insertions(+), 214 deletions(-) create mode 100644 .github/workflows/reusable-markdown-lint-check.yml create mode 100644 .markdownlint.yml diff --git a/.github/workflows/build-daily.yml b/.github/workflows/build-daily.yml index df13b95c34b8..4519c5cf9640 100644 --- a/.github/workflows/build-daily.yml +++ b/.github/workflows/build-daily.yml @@ -30,6 +30,9 @@ jobs: markdown-link-check: uses: ./.github/workflows/reusable-markdown-link-check.yml + markdown-lint-check: + uses: ./.github/workflows/reusable-markdown-lint-check.yml + misspell-check: uses: ./.github/workflows/reusable-misspell-check.yml diff --git a/.github/workflows/build-pull-request.yml b/.github/workflows/build-pull-request.yml index 4be43b5da3a4..19f485d216c2 100644 --- a/.github/workflows/build-pull-request.yml +++ b/.github/workflows/build-pull-request.yml @@ -43,6 +43,12 @@ jobs: if: "!startsWith(github.ref_name, 'release/')" uses: ./.github/workflows/reusable-markdown-link-check.yml + # this is a required check to avoid illegal markdown format + markdown-lint-check: + # release branches are excluded to avoid unnecessary maintenance + if: ${{ !startsWith(github.ref_name, 'release/') }} + uses: ./.github/workflows/reusable-markdown-lint-check.yml + # this is not a required check to avoid blocking pull requests if new misspellings are added # to the misspell dictionary misspell-check: diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index d08b9c9b4567..b480971e9fb7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -45,6 +45,11 @@ jobs: if: "!startsWith(github.ref_name, 'release/')" uses: ./.github/workflows/reusable-markdown-link-check.yml + markdown-lint-check: + # release branches are excluded + if: ${{ !startsWith(github.ref_name, 'release/') }} + uses: ./.github/workflows/reusable-markdown-lint-check.yml + misspell-check: # release branches are excluded to avoid unnecessary maintenance if new misspellings are added # to the misspell dictionary diff --git a/.github/workflows/reusable-markdown-lint-check.yml b/.github/workflows/reusable-markdown-lint-check.yml new file mode 100644 index 000000000000..c7cbf18086a9 --- /dev/null +++ b/.github/workflows/reusable-markdown-lint-check.yml @@ -0,0 +1,17 @@ +name: Reusable - Markdown lint check + +on: + workflow_call: + +jobs: + markdown-lint-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install mardkdownlint + run: npm install -g markdownlint-cli + + - name: Run markdownlint + run: | + markdownlint -c .markdownlint.yml -p .gitignore **/*.md -i licenses/licenses.md diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 000000000000..61e39a0a22fb --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,14 @@ +# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# and https://github.com/DavidAnson/markdownlint/blob/main/README.md + +# Default state for all rules +default: true + +ul-style: false +line-length: false +no-duplicate-header: + siblings_only: true +ol-prefix: + style: ordered +no-inline-html: false +fenced-code-language: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a98f47707733..fbb2c3c74ee8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -## Contributing +# Contributing Pull requests for bug fixes are always welcome! @@ -6,21 +6,21 @@ Before submitting new features or changes to current functionality, it is recomm [open an issue](https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/new) and discuss your ideas or propose the changes you wish to make. -### Building +## Building In order to build and test this whole repository you need JDK 11+. Some instrumentations and tests may put constraints on which java versions they support. See [Running the tests](./docs/contributing/running-tests.md) for more details. -#### Snapshot builds +### Snapshot builds For developers testing code changes before a release is complete, there are snapshot builds of the `main` branch. They are available from the Sonatype OSS snapshots repository at `https://oss.sonatype.org/content/repositories/snapshots/` ([browse](https://oss.sonatype.org/content/repositories/snapshots/io/opentelemetry/)) -#### Building from source +### Building from source Build using Java 11+: @@ -36,39 +36,39 @@ and then you can find the java agent artifact at `javaagent/build/libs/opentelemetry-javaagent-.jar`. -### IntelliJ setup and troubleshooting +## IntelliJ setup and troubleshooting See [IntelliJ setup and troubleshooting](docs/contributing/intellij-setup-and-troubleshooting.md) -### Style guide +## Style guide See [Style guide](docs/contributing/style-guideline.md) -### Running the tests +## Running the tests See [Running the tests](docs/contributing/running-tests.md) -### Writing instrumentation +## Writing instrumentation See [Writing instrumentation](docs/contributing/writing-instrumentation.md) -### Understanding the javaagent structure +## Understanding the javaagent structure See [Understanding the javaagent structure](docs/contributing/javaagent-structure.md) -### Understanding the javaagent instrumentation testing components +## Understanding the javaagent instrumentation testing components See [Understanding the javaagent instrumentation testing components](docs/contributing/javaagent-test-infra.md) -### Debugging +## Debugging See [Debugging](docs/contributing/debugging.md) -### Understanding Muzzle +## Understanding Muzzle See [Understanding Muzzle](docs/contributing/muzzle.md) -### Troubleshooting PR build failures +## Troubleshooting PR build failures The build logs are very long and there is a lot of parallelization, so the logs can be hard to decipher, but if you scroll to the bottom you should see something like: diff --git a/VERSIONING.md b/VERSIONING.md index 377e588f3496..b2475a72a265 100644 --- a/VERSIONING.md +++ b/VERSIONING.md @@ -3,7 +3,7 @@ ## Compatibility requirements Artifacts in this repository follow the same compatibility requirements described in -https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#compatibility-requirements + . EXCEPT for the following incompatible changes which are allowed in stable artifacts in this @@ -11,7 +11,7 @@ repository: * Changes to the telemetry produced by instrumentation (there will be some guarantees about telemetry stability in the future, see discussions - in https://github.com/open-telemetry/opentelemetry-specification/issues/1301) + in ) * Changes to configuration properties that contain the word `experimental` * Changes to configuration properties under the namespace `otel.javaagent.testing` @@ -23,7 +23,7 @@ This means that: ## Stable vs alpha -See https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md#stable-vs-alpha +See IN PARTICULAR: diff --git a/benchmark-overhead/README.md b/benchmark-overhead/README.md index fd248a053bd1..fe3fd11321f3 100644 --- a/benchmark-overhead/README.md +++ b/benchmark-overhead/README.md @@ -4,7 +4,7 @@ * [Process](#process) * [What do we measure?](#what-do-we-measure) * [Config](#config) - + [Agents](#agents) +* [Agents](#agents) * [Automation](#automation) * [Setup and Usage](#setup-and-usage) * [Visualization](#visualization) @@ -23,9 +23,10 @@ There is one dynamic test here called [OverheadTests](https://github.com/open-te The `@TestFactory` method creates a test pass for each of the [defined configurations](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/benchmark-overhead/src/test/java/io/opentelemetry/config/Configs.java). Before the tests run, a single collector instance is started. Each test pass has one or more agents configured and those are tested in series. For each agent defined in a configuration, the test runner (using [testcontainers](https://www.testcontainers.org/)) will: + 1. create a fresh postgres instance and populate it with initial data. 2. create a fresh instance of [spring-petclinic-rest](https://github.com/spring-petclinic/spring-petclinic-rest) instrumented with the specified agent -3. measure the time until the petclinic app is marked "healthy" and then write it to a file +3. measure the time until the petclinic app is marked "healthy" and then write it to a file. 4. if configured, perform a warmup phase. During the warmup phase, a bit of traffic is generated in order to get the application into a steady state (primarily helping facilitate jit compilations). Currently, we use a 30 second warmup time. 5. start a JFR recording by running `jcmd` inside the petclinic container 6. run the [k6 test script](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/benchmark-overhead/k6/basic.js) with the configured number of iterations through the file and the configured number of concurrent virtual users (VUs). @@ -65,6 +66,7 @@ relative overhead. ## Config Each config contains the following: + * name * description * list of agents (see below) @@ -74,6 +76,7 @@ Each config contains the following: * warmupSeconds - how long to wait before starting conducting measurements Currently, we test: + * no agent versus latest released agent * no agent versus latest snapshot * latest release vs. latest snapshot diff --git a/docs/contributing/debugging.md b/docs/contributing/debugging.md index ffb83cc15ce5..4ffeb53d9560 100644 --- a/docs/contributing/debugging.md +++ b/docs/contributing/debugging.md @@ -1,9 +1,9 @@ -## Debugging +# Debugging Debugging java agent can be a challenging task since some instrumentation code is directly inlined into target classes. -### Advice methods +## Advice methods Breakpoints do not work in advice methods, because their code is directly inlined by ByteBuddy into the target class. It is good to keep these methods as small as possible. @@ -21,13 +21,13 @@ System.out.println() Thread.dumpStack() ``` -### Agent initialization code +## Agent initialization code If you want to debug agent initialization code (e.g. `OpenTelemetryAgent`, `AgentInitializer`, `AgentInstaller`, `OpenTelemetryInstaller`, etc.) then it's important to specify the `-agentlib:` JVM arg before the `-javaagent:` JVM arg and use `suspend=y` (see full example below). -### Enabling debugging +## Enabling debugging The following example shows remote debugger configuration. The breakpoints should work in any code except ByteBuddy advice methods. diff --git a/docs/contributing/intellij-setup-and-troubleshooting.md b/docs/contributing/intellij-setup-and-troubleshooting.md index f4c03e2403df..7adfe30d6853 100644 --- a/docs/contributing/intellij-setup-and-troubleshooting.md +++ b/docs/contributing/intellij-setup-and-troubleshooting.md @@ -17,7 +17,7 @@ Configuration: ![enable google format](https://user-images.githubusercontent.com/5099946/131759832-36437aa0-a5f7-42c0-9425-8c5b45c16765.png) Note: If google-java-format generates errors in Intellij, -see https://github.com/google/google-java-format/issues/787#issuecomment-1200762464. +see . ## Troubleshooting diff --git a/docs/contributing/muzzle.md b/docs/contributing/muzzle.md index 76c2a8affc54..da880970359a 100644 --- a/docs/contributing/muzzle.md +++ b/docs/contributing/muzzle.md @@ -12,6 +12,7 @@ Muzzle will prevent loading an instrumentation if it detects any mismatch or con ## How it works Muzzle has two phases: + * at compile time it collects references to the third-party symbols and used helper classes; * at runtime it compares those references to the actual API symbols on the classpath. @@ -73,12 +74,15 @@ it's not an optional feature. The gradle plugin defines two tasks: * `muzzle` task runs the runtime muzzle verification against different library versions: + ```sh ./gradlew :instrumentation:google-http-client-1.19:javaagent:muzzle ``` + If a new, incompatible version of the instrumented library is published it fails the build. * `printMuzzleReferences` task prints all API references in a given module: + ```sh ./gradlew :instrumentation:google-http-client-1.19:javaagent:printMuzzleReferences ``` diff --git a/docs/contributing/repository-settings.md b/docs/contributing/repository-settings.md index fba8fc5d0381..f357f0bacea5 100644 --- a/docs/contributing/repository-settings.md +++ b/docs/contributing/repository-settings.md @@ -1,7 +1,7 @@ # Repository settings Repository settings in addition to what's documented already at -https://github.com/open-telemetry/community/blob/main/docs/how-to-configure-new-repository.md. +. ## General > Pull Requests diff --git a/docs/contributing/using-instrumenter-api.md b/docs/contributing/using-instrumenter-api.md index 9b3005f9df60..af7016afb669 100644 --- a/docs/contributing/using-instrumenter-api.md +++ b/docs/contributing/using-instrumenter-api.md @@ -413,7 +413,7 @@ In some rare cases it may be useful to completely disable the constructed `Instr example, based on a configuration property. The `InstrumenterBuilder` exposes a `setEnabled()` method for that: passing `false` will turn the newly created `Instrumenter` into a no-op instance. -### Finally, set the span kind with the `SpanKindExtractor` and get a new `Instrumenter`! +### Finally, set the span kind with the `SpanKindExtractor` and get a new `Instrumenter` The `Instrumenter` creation process ends with calling one of the following `InstrumenterBuilder` methods: diff --git a/docs/contributing/writing-instrumentation-module.md b/docs/contributing/writing-instrumentation-module.md index 566c7d2f24f2..7f145c08d251 100644 --- a/docs/contributing/writing-instrumentation-module.md +++ b/docs/contributing/writing-instrumentation-module.md @@ -344,14 +344,18 @@ compile time for it to work. ### Why we don't use ByteBuddy @Advice.Origin Method Instead of + ``` @Advice.Origin Method method ``` + we prefer to use + ``` @Advice.Origin("#t") Class declaringClass, @Advice.Origin("#m") String methodName ``` + because the former inserts a call to `Class.getMethod(...)` in transformed method. In contrast, getting the declaring class and method name is just loading constants from constant pool, which is a much simpler operation. diff --git a/docs/contributing/writing-instrumentation.md b/docs/contributing/writing-instrumentation.md index a4b6c41025bf..d320a7aa8b3a 100644 --- a/docs/contributing/writing-instrumentation.md +++ b/docs/contributing/writing-instrumentation.md @@ -359,6 +359,7 @@ That way you can use these shared, globally available utilities to communicate b instrumentation modules. Some examples of this include: + * Application server instrumentations communicating with Servlet API instrumentations. * Different high-level Kafka consumer instrumentations suppressing the low-level `kafka-clients` instrumentation. diff --git a/docs/java-7-rationale.md b/docs/java-7-rationale.md index 6922e8995dca..c8d320cd5357 100644 --- a/docs/java-7-rationale.md +++ b/docs/java-7-rationale.md @@ -1,6 +1,6 @@ -## Rationale for not supporting Java 7 +# Rationale for not supporting Java 7 -### Android support is no longer tied to Java 7 +## Android support is no longer tied to Java 7 Even for supporting old Android API levels: @@ -8,7 +8,7 @@ Even for supporting old Android API levels: > support for using a number of Java 8 language APIs without requiring a minimum API level for > your app. -(https://developer.android.com/studio/write/java8-support#library-desugaring) +() There are some Java 8 APIs that Android does not desugar, but we can use [animal sniffer plugin](https://github.com/xvik/gradle-animalsniffer-plugin) to ensure we don't use @@ -20,11 +20,11 @@ We will use this approach for the `instrumentation-api` module and for any libra instrumentation that would be useful to Android developers (e.g. library instrumentation for OkHttp). -### Modern test tooling requires Java 8+ +## Modern test tooling requires Java 8+ Both JUnit 5 and Testcontainers require Java 8+. -### Auto-instrumentation (Javaagent) +## Auto-instrumentation (Javaagent) We could run tests against Java 8+ and ensure Java 7 compliance by using similar animal sniffer technique as above. @@ -43,13 +43,13 @@ debugging across two separate JVMs. And new contributor experience has a very hi project (compared to say commercial tools who can invest more in onboarding their employees onto a more complex codebase). -### Library (manual) instrumentation +## Library (manual) instrumentation We believe that Java 7 users are primarily in maintenance mode and not interested in cracking open their code anymore and adding library (manual) instrumentation, so we don't believe there is much interest in library instrumentation targeting Java 7. -### Java 7 usage +## Java 7 usage Certainly one factor to consider is what percentage of production applications are running Java 7. @@ -57,7 +57,7 @@ Luckily, New Relic [published their numbers recently](https://blog.newrelic.com/technology/state-of-java), so we know that ~2.5% of production applications are still running Java 7 as of March 2020. -### Alternatives for Java 7 users +## Alternatives for Java 7 users We understand the situations that lead applications to get stuck on Java 7 (we've been there ourselves), and we agree that those applications need monitoring too. diff --git a/docs/logger-mdc-instrumentation.md b/docs/logger-mdc-instrumentation.md index e57fed0d3c6f..34255a3f4317 100644 --- a/docs/logger-mdc-instrumentation.md +++ b/docs/logger-mdc-instrumentation.md @@ -22,6 +22,7 @@ Those three pieces of information can be included in log statements produced by by specifying them in the pattern/format. Tip: for Spring Boot configuration which uses logback, you can add MDC to log lines by overriding only the `logging.pattern.level`: + ```properties logging.pattern.level = trace_id=%mdc{trace_id} span_id=%mdc{span_id} trace_flags=%mdc{trace_flags} %5p ``` diff --git a/docs/misc/inter-thread-context-propagation.md b/docs/misc/inter-thread-context-propagation.md index 0c25a569a902..54882f28334f 100644 --- a/docs/misc/inter-thread-context-propagation.md +++ b/docs/misc/inter-thread-context-propagation.md @@ -1,6 +1,7 @@ # The story of context propagation across threads ## The need + Take a look at the following two pseudo-code snippets (see below for explanations). ``` @@ -42,6 +43,7 @@ parent-child relationship between span: span representing shipping address query of the span which denotes accepting HTTP request. ## The solution + Java auto instrumentation uses an obvious solution to the requirement above: we attach current execution context (represented in the code by `Context`) with each `Runnable`, `Callable` and `ForkJoinTask`. "Current" means the context active on the thread which calls `Executor.execute` (and its analogues @@ -60,7 +62,9 @@ on that thread for the duration of the execution. This can be illustrated by the ``` ## The drawback + Here is a simplified example of what async servlet processing may look like + ``` protected void service(HttpServletRequest req, HttpServletResponse resp) { //This method is instrumented and we start new scope here @@ -75,6 +79,7 @@ protected void service(HttpServletRequest req, HttpServletResponse resp) { } } ``` + If we now take a look inside `context.complete` method from above it may be implemented like this: ``` @@ -97,6 +102,7 @@ to huge traces being active for hours and hours. In addition this makes some of our tests extremely flaky. ## The currently accepted trade-offs + We acknowledge the problem with too active context propagation. We still think that out of the box support for asynchronous multi-threaded traces is very important. We have diagnostics in place to help us with detecting when we too eagerly propagate the execution context too far. We hope to diff --git a/docs/misc/interop-design/interop-design.md b/docs/misc/interop-design/interop-design.md index 1d675b6795f0..11cfccfec34e 100644 --- a/docs/misc/interop-design/interop-design.md +++ b/docs/misc/interop-design/interop-design.md @@ -61,11 +61,11 @@ Different vendors will provide their own exporter here. There may be an option for users to bring their own (unshaded) OpenTelemetry Exporter and have the agent perform the required shading on the fly. -#### Open Questions +### Open Questions If there are multiple apps running in the same JVM, how to distinguish between them? -#### Risks +### Risks User code could cast OpenTelemetry API objects to the underlying OpenTelemetry SDK classes, which would throw ClassCastException if it finds the Versioned Bridge class instead. @@ -86,7 +86,7 @@ The Java agent could check which version of the OpenTelemetry API was brought by and only apply the bytecode instrumentation if it's compatible with that version of the OpenTelemetry API. -#### Advantages +### Advantages Users who have performed programmatic configuration of the SDK / exporter do not lose that configuration. @@ -94,7 +94,7 @@ do not lose that configuration. If there are multiple apps running in the same JVM, it's easy to distinguish them since they can each have their own SDK / exporter configuration. -#### Disadvantages +### Disadvantages Classes outside of the user app cannot be instrumented since those classes do not have access to the OpenTelemetry API brought by the user app. This includes classes brought by the JVM @@ -114,11 +114,11 @@ This would work by having new server/consumer spans set the Class Loader Bridge so that instrumentation on all classes during that span would be able to look up the bridge and emit telemetry. -#### Advantages +### Advantages Same as Alternate Design 1 above -#### Disadvantages +### Disadvantages Bytecode instrumentation on classes outside of the user app cannot emit any telemetry if there is not already an active span. This includes classes brought by the JVM @@ -130,4 +130,4 @@ and the application server (e.g. HttpServlet and other Java EE classes). [1] Shading dependencies is the process of including and renaming dependencies (thus relocating the classes & rewriting affected bytecode & resources) to create a private copy that you bundle alongside your own code -(https://softwareengineering.stackexchange.com/questions/297276/what-is-a-shaded-java-dependency) +() diff --git a/docs/scope.md b/docs/scope.md index 1a22a0871f23..be1ed2c17d28 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -1,4 +1,4 @@ -### Scope of this repository +# Scope of this repository Both javaagent and library-based approaches to the following: diff --git a/docs/semantic-conventions.md b/docs/semantic-conventions.md index 378fb105996d..b1883e7e490d 100644 --- a/docs/semantic-conventions.md +++ b/docs/semantic-conventions.md @@ -29,7 +29,6 @@ capture `http.url`. **[2]:** In case of Armeria, return values are [SessionProtocol](https://github.com/line/armeria/blob/master/core/src/main/java/com/linecorp/armeria/common/SessionProtocol.java), not values defined by spec. - ## Http Client | Attribute | Required | Implemented? | diff --git a/docs/supported-libraries.md b/docs/supported-libraries.md index a91ddae9a526..3240e508e581 100644 --- a/docs/supported-libraries.md +++ b/docs/supported-libraries.md @@ -8,10 +8,10 @@ or [contributing](../CONTRIBUTING.md). ## Contents - * [Libraries / Frameworks](#libraries--frameworks) - * [Application Servers](#application-servers) - * [JVMs and Operating Systems](#jvms-and-operating-systems) - * [Disabled instrumentations](#disabled-instrumentations) +* [Libraries / Frameworks](#libraries--frameworks) +* [Application Servers](#application-servers) +* [JVMs and Operating Systems](#jvms-and-operating-systems) +* [Disabled instrumentations](#disabled-instrumentations) ## Libraries / Frameworks @@ -141,12 +141,10 @@ These are the supported libraries and frameworks: [RPC Server Metrics]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/rpc-metrics.md#rpc-server [RPC Client Metrics]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/rpc-metrics.md#rpc-client [Messaging Spans]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/messaging.md -[Database Spans]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/db.md [Database Pool Metrics]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/database-metrics.md [JVM Runtime Metrics]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/runtime-environment-metrics.md#jvm-metrics [System Metrics]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/system-metrics.md - ## Application Servers These are the application servers that the smoke tests are run against: diff --git a/examples/distro/README.md b/examples/distro/README.md index 205032a2dfbd..4ed7a2fe6975 100644 --- a/examples/distro/README.md +++ b/examples/distro/README.md @@ -1,3 +1,5 @@ +# Distro + ## Introduction This repository serves as a collection of examples of extending functionality of OpenTelemetry Java instrumentation agent. @@ -35,14 +37,17 @@ As an example, let us take some database client instrumentation that creates a s and extracts data from db connection to provide attributes for that span. ### I don't want this span at all + The easiest case. You can just pre-configure your distribution and disable given instrumentation. -### I want to add/modify some attributes and their values does NOT depend on a specific db connection instance. +### I want to add/modify some attributes and their values does NOT depend on a specific db connection instance + E.g. you want to add some data from call stack as span attribute. In this case just provide your custom `SpanProcessor`. No need for touching instrumentation itself. -### I want to add/modify some attributes and their values depend on a specific db connection instance. +### I want to add/modify some attributes and their values depend on a specific db connection instance + Write a _new_ instrumentation which injects its own advice into the same method as the original one. Use `getOrder` method to ensure it is run after the original instrumentation. Now you can augment current span with new information. @@ -50,9 +55,11 @@ Now you can augment current span with new information. See [DemoServlet3Instrumentation](instrumentation/servlet-3/src/main/java/com/example/javaagent/instrumentation/DemoServlet3Instrumentation.java). ### I want to remove some attributes + Write custom exporter or use attribute filtering functionality in Collector. ### I don't like Otel span at all. I want to significantly modify it and its lifecycle + Disable existing instrumentation. Write a new one, which injects `Advice` into the same (or better) method as the original instrumentation. Write your own `Advice` for this. diff --git a/examples/extension/README.md b/examples/extension/README.md index 76955726aebf..35d5af4b6b4e 100644 --- a/examples/extension/README.md +++ b/examples/extension/README.md @@ -1,3 +1,5 @@ +# Extensions + ## Introduction Extensions add new features and capabilities to the agent without having to create a separate distribution (for examples and ideas, see [Use cases for extensions](#sample-use-cases)). @@ -20,6 +22,7 @@ To add the extension to the instrumentation agent: -Dotel.javaagent.extensions=build/libs/opentelemetry-java-instrumentation-extension-demo-1.0-all.jar -jar myapp.jar ``` + Note: to load multiple extensions, you can specify a comma-separated list of extension jars or directories (that contain extension jars) for the `otel.javaagent.extensions` value. @@ -28,6 +31,7 @@ contain extension jars) for the `otel.javaagent.extensions` value. To simplify deployment, you can embed extensions into the OpenTelemetry Java Agent to produce a single jar file. With an integrated extension, you no longer need the `-Dotel.javaagent.extensions` command line option. For more information, see the `extendedAgent` task in [build.gradle](build.gradle). + ## Extensions examples * Custom `IdGenerator`: [DemoIdGenerator](src/main/java/com/example/javaagent/DemoIdGenerator.java) diff --git a/instrumentation/apache-dbcp-2.0/library/README.md b/instrumentation/apache-dbcp-2.0/library/README.md index c7c6d44e4011..04c3e98c3764 100644 --- a/instrumentation/apache-dbcp-2.0/library/README.md +++ b/instrumentation/apache-dbcp-2.0/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [Apache DBCP](https://commons.apache. ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-apache-dbcp-2.0). diff --git a/instrumentation/aws-lambda/aws-lambda-core-1.0/library/README.md b/instrumentation/aws-lambda/aws-lambda-core-1.0/library/README.md index 5752554a0dca..3cbbda415d96 100644 --- a/instrumentation/aws-lambda/aws-lambda-core-1.0/library/README.md +++ b/instrumentation/aws-lambda/aws-lambda-core-1.0/library/README.md @@ -3,17 +3,20 @@ This package contains libraries to help instrument AWS lambda functions in your code. ## Using wrappers + To use the instrumentation, configure `OTEL_INSTRUMENTATION_AWS_LAMBDA_HANDLER` env property to your lambda handler method in following format `package.ClassName::methodName` and use one of wrappers as your lambda `Handler`. In order to configure a span flush timeout (default is set to 1 second), please configure `OTEL_INSTRUMENTATION_AWS_LAMBDA_FLUSH_TIMEOUT` env property. The value is in seconds. Available wrappers: + - `io.opentelemetry.instrumentation.awslambdacore.v1_0.TracingRequestStreamWrapper` - for wrapping streaming handlers (implementing `RequestStreamHandler`), enabling HTTP context propagation for HTTP requests When using known Lambda event types as parameters, use [aws-lambda-events-2.2](../../aws-lambda-events-2.2/library). ## Using handlers + To use the instrumentation, replace your function classes that implement `RequestHandler` (or `RequestStreamHandler`) with those that extend `TracingRequestHandler` (or `TracingRequestStreamHandler`). You will need to change the method name to `doHandleRequest` and pass an initialized `OpenTelemetrySdk` to the base class. @@ -67,21 +70,22 @@ Maven: ``` - ## Trace propagation Context propagation for this instrumentation can be done either with X-Ray propagation or regular HTTP propagation. If X-Ray is enabled for instrumented lambda, it will be preferred. If X-Ray is disabled, HTTP propagation will be tried (that is HTTP headers will be read to check for a valid trace context). - ### X-Ray propagation + This instrumentation supports propagating traces using the `X-Amzn-Trace-Id` format for both normal requests and SQS requests. X-Ray propagation is always enabled, there is no need to configure it explicitly. ### HTTP headers based propagation + For API Gateway (HTTP) requests instrumented by using one of following methods: + - extending `TracingRequestStreamHandler` or `TracingRequestHandler` - wrapping with `TracingRequestStreamWrapper` or `TracingRequestApiGatewayWrapper` -traces can be propagated with supported HTTP headers (see https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace-propagators). +traces can be propagated with supported HTTP headers (see ). In order to enable requested propagation for a handler, configure it on the SDK you build. diff --git a/instrumentation/aws-lambda/aws-lambda-events-2.2/library/README.md b/instrumentation/aws-lambda/aws-lambda-events-2.2/library/README.md index c812b01a50d9..c200496bbdf0 100644 --- a/instrumentation/aws-lambda/aws-lambda-events-2.2/library/README.md +++ b/instrumentation/aws-lambda/aws-lambda-events-2.2/library/README.md @@ -3,12 +3,14 @@ This package contains libraries to help instrument AWS lambda functions in your code. ## Using wrappers + To use the instrumentation, configure `OTEL_INSTRUMENTATION_AWS_LAMBDA_HANDLER` env property to your lambda handler method in following format `package.ClassName::methodName` and use one of wrappers as your lambda `Handler`. In order to configure a span flush timeout (default is set to 1 second), please configure `OTEL_INSTRUMENTATION_AWS_LAMBDA_FLUSH_TIMEOUT` env property. The value is in seconds. Available wrappers: + - `io.opentelemetry.instrumentation.awslambdaevents.v2_2.TracingRequestWrapper` - for wrapping regular handlers (implementing `RequestHandler`) - `io.opentelemetry.instrumentation.awslambdaevents.v2_2.TracingRequestApiGatewayWrapper` - for wrapping regular handlers (implementing `RequestHandler`) proxied through API Gateway, enabling HTTP context propagation - `io.opentelemetry.instrumentation.awslambdacore.v1_0.TracingRequestStreamWrapper` - for wrapping streaming handlers (implementing `RequestStreamHandler`), enabling HTTP context propagation for HTTP requests @@ -17,6 +19,7 @@ If you are only using `TracingRequestStreamWrapper`, consider using [aws-lambda- your compiled function. ## Using handlers + To use the instrumentation, replace your function classes that implement `RequestHandler` (or `RequestStreamHandler`) with those that extend `TracingRequestHandler` (or `TracingRequestStreamHandler`). You will need to change the method name to `doHandleRequest` and pass an initialized `OpenTelemetrySdk` to the base class. @@ -51,6 +54,7 @@ link to tracing information provided by Lambda itself. To do so, add a dependenc you use. Gradle: + ```kotlin dependencies { implementation("io.opentelemetry:opentelemetry-extension-trace-propagators:0.8.0") @@ -103,16 +107,18 @@ public class MyBatchHandler extends TracingSQSEventHandler { Context propagation for this instrumentation can be done either with X-Ray propagation or regular HTTP propagation. If X-Ray is enabled for instrumented lambda, it will be preferred. If X-Ray is disabled, HTTP propagation will be tried (that is HTTP headers will be read to check for a valid trace context). - ### X-Ray propagation + This instrumentation supports propagating traces using the `X-Amzn-Trace-Id` format for both normal requests and SQS requests. X-Ray propagation is always enabled, there is no need to configure it explicitly. ### HTTP headers based propagation + For API Gateway (HTTP) requests instrumented by using one of following methods: + - extending `TracingRequestStreamHandler` or `TracingRequestHandler` - wrapping with `TracingRequestStreamWrapper` or `TracingRequestApiGatewayWrapper` -traces can be propagated with supported HTTP headers (see https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/trace-propagators). +traces can be propagated with supported HTTP headers (see ). In order to enable requested propagation for a handler, configure it on the SDK you build. diff --git a/instrumentation/c3p0-0.9/library/README.md b/instrumentation/c3p0-0.9/library/README.md index ebfb4960a5e1..55ac8d775ffe 100644 --- a/instrumentation/c3p0-0.9/library/README.md +++ b/instrumentation/c3p0-0.9/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [C3P0](https://www.mchange.com/projec ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-c3p0-0.9). diff --git a/instrumentation/external-annotations/README.md b/instrumentation/external-annotations/README.md index 267a850c6862..143dbcbdd572 100644 --- a/instrumentation/external-annotations/README.md +++ b/instrumentation/external-annotations/README.md @@ -1,6 +1,6 @@ # Settings for the external annotations instrumentation -| System property | Type | Default | Description | -|----------------- |------ |--------- |------------- | -| `otel.instrumentation.external-annotations.include` | String | Default annotations | Configuration for trace annotations, in the form of a pattern that matches `'package.Annotation$Name;*'`. +| System property | Type | Default | Description | +|----------------- |------ |--------- |------------- | +| `otel.instrumentation.external-annotations.include` | String | Default annotations | Configuration for trace annotations, in the form of a pattern that matches `'package.Annotation$Name;*'`. | `otel.instrumentation.external-annotations.exclude-methods` | String | | All methods to be excluded from auto-instrumentation by annotation-based advices. | diff --git a/instrumentation/graphql-java-12.0/library/README.md b/instrumentation/graphql-java-12.0/library/README.md index 9aec4e022977..40ef49479d3c 100644 --- a/instrumentation/graphql-java-12.0/library/README.md +++ b/instrumentation/graphql-java-12.0/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [GraphQL Java](https://www.graphql-ja ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-graphql-java-12.0). diff --git a/instrumentation/grpc-1.6/library/README.md b/instrumentation/grpc-1.6/library/README.md index 0f4cdef3bde9..ab574d251496 100644 --- a/instrumentation/grpc-1.6/library/README.md +++ b/instrumentation/grpc-1.6/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [gRPC](https://grpc.io/). ## Quickstart -### Add the following dependencies to your project: +### Add the following dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-grpc-1.6). diff --git a/instrumentation/hikaricp-3.0/library/README.md b/instrumentation/hikaricp-3.0/library/README.md index a403308f9929..233b5c6e8956 100644 --- a/instrumentation/hikaricp-3.0/library/README.md +++ b/instrumentation/hikaricp-3.0/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [HikariCP](https://github.com/brettwo ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-hikaricp-3.0). diff --git a/instrumentation/jdbc/library/README.md b/instrumentation/jdbc/library/README.md index 383074109019..2ab0051ee709 100644 --- a/instrumentation/jdbc/library/README.md +++ b/instrumentation/jdbc/library/README.md @@ -5,7 +5,7 @@ Provides OpenTelemetry instrumentation for ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-jdbc). @@ -65,14 +65,10 @@ public class DataSourceConfig { #### Driver way -1. Activate tracing for JDBC connections by setting `jdbc:otel:` prefix to the JDBC URL: - -``` -jdbc:otel:h2:mem:test -``` +1. Activate tracing for JDBC connections by setting `jdbc:otel:` prefix to the JDBC URL, e.g. `jdbc:otel:h2:mem:test`. 2. Set the driver class to `io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver` and initialize the driver with: -```java -Class.forName("io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver"); -``` + ```java + Class.forName("io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver"); + ``` diff --git a/instrumentation/jetty/README.md b/instrumentation/jetty/README.md index afbb8679db3e..17fa8aaa2168 100644 --- a/instrumentation/jetty/README.md +++ b/instrumentation/jetty/README.md @@ -1,6 +1,7 @@ # Instrumentation for Jetty request handlers Jetty support is divided into the following sub-modules: + - `jetty-common:javaagent` contains common type instrumentation and advice helper classes used by the `javaagent` modules of all supported Jetty versions - `jetty-8.0:javaagent` applies Jetty request handler instrumentation for versions `[8, 11)` diff --git a/instrumentation/jmx-metrics/javaagent/README.md b/instrumentation/jmx-metrics/javaagent/README.md index c2eef2a60c8b..eaf2f69c54f5 100644 --- a/instrumentation/jmx-metrics/javaagent/README.md +++ b/instrumentation/jmx-metrics/javaagent/README.md @@ -23,12 +23,12 @@ $ java -javaagent:path/to/opentelemetry-javaagent.jar \ No targets are enabled by default. The supported target environments are listed below. - - [activemq](activemq.md) - - [jetty](jetty.md) - - [kafka-broker](kafka-broker.md) - - [tomcat](tomcat.md) - - [wildfly](wildfly.md) - - [hadoop](hadoop.md) +- [activemq](activemq.md) +- [jetty](jetty.md) +- [kafka-broker](kafka-broker.md) +- [tomcat](tomcat.md) +- [wildfly](wildfly.md) +- [hadoop](hadoop.md) ## Configuration File @@ -44,6 +44,7 @@ $ java -javaagent:path/to/opentelemetry-javaagent.jar \ ### Basic Syntax The configuration file can contain multiple entries (which we call _rules_), defining a number of metrics. Each rule must identify a set of MBeans and the name of the MBean attribute to query, along with additional information on how to report the values. Let's look at a simple example. + ```yaml --- rules: @@ -55,6 +56,7 @@ rules: desc: The current number of threads unit: 1 ``` + MBeans are identified by unique [ObjectNames](https://docs.oracle.com/javase/8/docs/api/javax/management/ObjectName.html). In the example above, the object name `java.lang:type=Threading` identifies one of the standard JVM MBeans, which can be used to access a number of internal JVM statistics related to threads. For that MBean, we specify its attribute `ThreadCount` which reflects the number of currently active (alive) threads. The values of this attribute will be reported by a metric named `my.own.jvm.thread.count`. The declared OpenTelemetry type of the metric is declared as `updowncounter` which indicates that the value is a sum which can go up or down over time. Metric description and/or unit can also be specified. All metrics reported by the service are backed by @@ -68,6 +70,7 @@ To figure out what MBeans (or ObjectNames) and their attributes are available fo ### Composite Types The next example shows how the current heap size can be reported. + ```yaml --- rules: @@ -84,6 +87,7 @@ rules: desc: The maximum allowed heap size unit: By ``` + The MBean responsible for memory statistics, identified by ObjectName `java.lang:type=Memory` has an attribute named `HeapMemoryUsage`, which is of a `CompositeType`. This type represents a collection of fields with values (very much like the traditional `struct` data type). To access individual fields of the structure we use a dot which separates the MBean attribute name from the field name. The values are reported in bytes, which here we indicate by `By`. In the above example, the current heap size and the maximum allowed heap size will be reported as two metrics, named `my.own.jvm.heap.used`, and `my.own.jvm.heap.max`. ### Measurement Attributes @@ -113,14 +117,15 @@ rules: The ObjectName pattern will match a number of MBeans, each for a different memory pool. The number and names of available memory pools, however, will be known only at runtime. To report values for all actual memory pools using only two metrics, we use metric attributes (referenced by the configuration file as `metricAttribute` elements). The first metric attribute, named `pool` will have its value derived from the ObjectName parameter `name` - which corresponds to the memory pool name. The second metric attribute, named `type` will get its value from the corresponding MBean attribute named `Type`. The values of this attribute are strings `HEAP` or `NON_HEAP` classifying the corresponding memory pool. Here the definition of the metric attributes is shared by both metrics, but it is also possible to define them at the individual metric level. Using the above rule, when running on HotSpot JVM for Java 11, the following combinations of metric attributes will be reported. - - {pool="Compressed Class Space", type="NON_HEAP"} - - {pool="CodeHeap 'non-profiled nmethods'", type="NON_HEAP"} - - {pool="G1 Eden Space", type="HEAP"} - - {pool="G1 Old Gen", type="HEAP"} - - {pool="CodeHeap 'profiled nmethods'", type="NON_HEAP"} - - {pool="Metaspace", type="NON_HEAP"} - - {pool="CodeHeap 'non-nmethods'", type="NON_HEAP"} - - {pool="G1 Survivor Space", type="HEAP"} + +- {pool="Compressed Class Space", type="NON_HEAP"} +- {pool="CodeHeap 'non-profiled nmethods'", type="NON_HEAP"} +- {pool="G1 Eden Space", type="HEAP"} +- {pool="G1 Old Gen", type="HEAP"} +- {pool="CodeHeap 'profiled nmethods'", type="NON_HEAP"} +- {pool="Metaspace", type="NON_HEAP"} +- {pool="CodeHeap 'non-nmethods'", type="NON_HEAP"} +- {pool="G1 Survivor Space", type="HEAP"} **Note**: Heap and memory pool metrics above are given just as examples. The Java Agent already reports such metrics, no additional configuration is needed from the users. @@ -149,6 +154,7 @@ rules: desc: The number of transmitted bytes unit: By ``` + The referenced MBean has two attributes of interest, `bytesReceived`, and `bytesSent`. We want them to be reported by just one metric, but keeping the values separate by using metric attribute `direction`. This is achieved by specifying the same metric name `catalina.traffic` when mapping the MBean attributes to metrics. There will be two metric attributes provided: `handler`, which has a shared definition, and `direction`, which has its value (`in` or `out`) declared directly as constants, depending on the MBean attribute providing the metric value. Keep in mind that when defining a metric multiple times like this, its type, unit and description must be exactly the same. Otherwise there will be complaints about attempts to redefine a metric in a non-compatible way. @@ -206,6 +212,7 @@ rules: task-created-total: task-closed-total: ``` + Because we declared metric prefix (here `my.kafka.streams.`) and did not specify actual metric names, the metric names will be generated automatically, by appending the corresponding MBean attribute name to the prefix. Thus, the above definitions will create several metrics, named `my.kafka.streams.commit-latency-avg`, `my.kafka.streams.commit-latency-max`, and so on. For the first configuration rule, the default unit has been changed to `ms`, which remains in effect for all MBean attribute mappings listed within the rule, unless they define their own unit. Similarly, the second configuration rule defines the unit as `/s`, valid for all the rates reported. @@ -247,6 +254,7 @@ rules: # start of list of configuration rules type: updowncounter # optional : # metric name will be ``` + The following table explains the used terms with more details. | Syntactic Element | Description | diff --git a/instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md b/instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md index b25804f432cb..64481b7ac7b9 100644 --- a/instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md +++ b/instrumentation/kafka/kafka-clients/kafka-clients-2.6/library/README.md @@ -2,7 +2,7 @@ ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-kafka-clients-2.6). diff --git a/instrumentation/kotlinx-coroutines/README.md b/instrumentation/kotlinx-coroutines/README.md index d636674ab8f7..4e368921be91 100644 --- a/instrumentation/kotlinx-coroutines/README.md +++ b/instrumentation/kotlinx-coroutines/README.md @@ -1,2 +1,4 @@ +# Kotlin Coroutines + Kotlin coroutine library instrumentation is located at -https://github.com/open-telemetry/opentelemetry-java/tree/main/extensions/kotlin + diff --git a/instrumentation/ktor/ktor-1.0/library/README.md b/instrumentation/ktor/ktor-1.0/library/README.md index 1d48805630fb..492954f86f2c 100644 --- a/instrumentation/ktor/ktor-1.0/library/README.md +++ b/instrumentation/ktor/ktor-1.0/library/README.md @@ -4,7 +4,7 @@ This package contains libraries to help instrument Ktor. Currently, only server ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-ktor-1.0). diff --git a/instrumentation/ktor/ktor-2.0/library/README.md b/instrumentation/ktor/ktor-2.0/library/README.md index 6fcad026de96..b1343d9060a8 100644 --- a/instrumentation/ktor/ktor-2.0/library/README.md +++ b/instrumentation/ktor/ktor-2.0/library/README.md @@ -4,7 +4,7 @@ This package contains libraries to help instrument Ktor. Currently, only server ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-ktor-2.0). diff --git a/instrumentation/log4j/log4j-appender-2.17/library/README.md b/instrumentation/log4j/log4j-appender-2.17/library/README.md index e8d261c0ffda..de35db0e03d6 100644 --- a/instrumentation/log4j/log4j-appender-2.17/library/README.md +++ b/instrumentation/log4j/log4j-appender-2.17/library/README.md @@ -6,7 +6,7 @@ which forwards Log4j2 log events to the ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-log4j-appender-2.17). diff --git a/instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure/README.md b/instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure/README.md index 027df75c1d88..5d4c761a3106 100644 --- a/instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure/README.md +++ b/instrumentation/log4j/log4j-context-data/log4j-context-data-2.17/library-autoconfigure/README.md @@ -5,7 +5,7 @@ into log context. ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-log4j-context-data-2.17-autoconfigure). diff --git a/instrumentation/logback/logback-appender-1.0/library/README.md b/instrumentation/logback/logback-appender-1.0/library/README.md index 05a010b7b77d..6107ff0aea7e 100644 --- a/instrumentation/logback/logback-appender-1.0/library/README.md +++ b/instrumentation/logback/logback-appender-1.0/library/README.md @@ -6,7 +6,7 @@ forwards Logback log events to the ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-logback-appender-1.0). diff --git a/instrumentation/logback/logback-mdc-1.0/library/README.md b/instrumentation/logback/logback-mdc-1.0/library/README.md index d395d455e646..ba570686c628 100644 --- a/instrumentation/logback/logback-mdc-1.0/library/README.md +++ b/instrumentation/logback/logback-mdc-1.0/library/README.md @@ -5,7 +5,7 @@ mounted span using a custom Logback appender. ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-logback-mdc-1.0). @@ -32,7 +32,7 @@ dependencies { ### Usage -**logback.xml** +logback.xml: ```xml diff --git a/instrumentation/methods/README.md b/instrumentation/methods/README.md index d453edc477a2..217691c322a7 100644 --- a/instrumentation/methods/README.md +++ b/instrumentation/methods/README.md @@ -1,7 +1,7 @@ # Settings for the methods instrumentation -| System property | Type | Default | Description | -|----------------- |------ |--------- |------------- | +| System property | Type | Default | Description | +|----------------- |------ |--------- |------------- | | `otel.instrumentation.methods.include` | String| None | List of methods to include for tracing. For more information, see [Creating spans around methods with `otel.instrumentation.methods.include`][cs]. [cs]: https://opentelemetry.io/docs/instrumentation/java/annotations/#creating-spans-around-methods-with-otelinstrumentationmethodsinclude diff --git a/instrumentation/okhttp/okhttp-3.0/library/README.md b/instrumentation/okhttp/okhttp-3.0/library/README.md index f797974f3228..8ea3103e6f28 100644 --- a/instrumentation/okhttp/okhttp-3.0/library/README.md +++ b/instrumentation/okhttp/okhttp-3.0/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [okhttp3](https://square.github.io/ok ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-okhttp-3.0). diff --git a/instrumentation/opentelemetry-extension-annotations-1.0/README.md b/instrumentation/opentelemetry-extension-annotations-1.0/README.md index 13b23c4d71c7..6c4aae743ffa 100644 --- a/instrumentation/opentelemetry-extension-annotations-1.0/README.md +++ b/instrumentation/opentelemetry-extension-annotations-1.0/README.md @@ -1,5 +1,5 @@ # Settings for the OpenTelemetry Extension Annotations integration -| Environment variable | Type | Default | Description | -|----------------- |------ |--------- |------------- | +| Environment variable | Type | Default | Description | +|----------------- |------ |--------- |------------- | | `otel.instrumentation.opentelemetry-annotations.exclude-methods` | String | | All methods to be excluded from auto-instrumentation by annotation-based advices. | diff --git a/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md b/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md index c62df30724a5..ca1f2498c920 100644 --- a/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md +++ b/instrumentation/opentelemetry-instrumentation-annotations-1.16/README.md @@ -1,5 +1,5 @@ # Settings for the OpenTelemetry Instrumentation Annotations integration -| Environment variable | Type | Default | Description | -|----------------- |------ |--------- |------------- | +| Environment variable | Type | Default | Description | +|----------------- |------ |--------- |------------- | | `otel.instrumentation.opentelemetry-instrumentation-annotations.exclude-methods` | String | | All methods to be excluded from auto-instrumentation by annotation-based advices. | diff --git a/instrumentation/oracle-ucp-11.2/library/README.md b/instrumentation/oracle-ucp-11.2/library/README.md index f16f2309cc22..cbc3eefa4335 100644 --- a/instrumentation/oracle-ucp-11.2/library/README.md +++ b/instrumentation/oracle-ucp-11.2/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [Oracle UCP](https://docs.oracle.com/ ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-oracle-ucp-11.2). diff --git a/instrumentation/resources/library/README.md b/instrumentation/resources/library/README.md index d72b3f09d9b4..9e377ded6908 100644 --- a/instrumentation/resources/library/README.md +++ b/instrumentation/resources/library/README.md @@ -9,18 +9,20 @@ common environments. Currently, the resources provide the following semantic con Provider: `io.opentelemetry.instrumentation.resources.ContainerResource` -Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/container.md +Specification: Implemented attributes: + - `container.id` ### Host Provider: `io.opentelemetry.instrumentation.resources.HostResource` -Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/host.md +Specification: Implemented attributes: + - `host.name` - `host.arch` @@ -28,9 +30,10 @@ Implemented attributes: Provider: `io.opentelemetry.instrumentation.resources.OsResource` -Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/resource/semantic_conventions/os.md +Specification: Implemented attributes: + - `os.type` - `os.description` @@ -38,9 +41,10 @@ Implemented attributes: Implementation: `io.opentelemetry.instrumentation.resources.ProcessResource` -Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/resource/semantic_conventions/process.md#process +Specification: Implemented attributes: + - `process.pid` - `process.executable.path` (note, we assume the `java` binary is located in the `bin` subfolder of `JAVA_HOME`) - `process.command_line` (note this includes all system properties and arguments when running) @@ -49,9 +53,10 @@ Implemented attributes: Implementation: `io.opentelemetry.instrumentation.resources.ProcessRuntimeResource` -Specification: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/resource/semantic_conventions/process.md#process-runtimes +Specification: Implemented attributes: + - `process.runtime.name` - `process.runtime.version` - `process.runtime.description` diff --git a/instrumentation/rocketmq/rocketmq-client/rocketmq-client-4.8/library/README.md b/instrumentation/rocketmq/rocketmq-client/rocketmq-client-4.8/library/README.md index 9f8fb41c3426..7844d4d0d286 100644 --- a/instrumentation/rocketmq/rocketmq-client/rocketmq-client-4.8/library/README.md +++ b/instrumentation/rocketmq/rocketmq-client/rocketmq-client-4.8/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [Apache RocketMQ](https://rocketmq.ap ## Quickstart -### Add the following dependencies to your project: +### Add the following dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-rocketmq-client-4.8). diff --git a/instrumentation/runtime-metrics/library/README.md b/instrumentation/runtime-metrics/library/README.md index 6155cd79b1d7..cb42c414d2e2 100644 --- a/instrumentation/runtime-metrics/library/README.md +++ b/instrumentation/runtime-metrics/library/README.md @@ -4,7 +4,7 @@ This module provides JVM runtime metrics as documented in the [semantic conventi ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-runtime-metrics). diff --git a/instrumentation/servlet/README.md b/instrumentation/servlet/README.md index c0ca92d47359..c9c0ba87cd5e 100644 --- a/instrumentation/servlet/README.md +++ b/instrumentation/servlet/README.md @@ -1,18 +1,19 @@ # Instrumentation for Java Servlets -# Settings +## Settings | System property | Type | Default | Description | |---|---|---|---| | `otel.instrumentation.servlet.experimental-span-attributes` | Boolean | `false` | Enable the capture of experimental span attributes. | | `otel.instrumentation.servlet.experimental.capture-request-parameters` | List | Empty | Request parameters to be captured (experimental). | -## A word about version +### A word about version We support Servlet API starting from version 2.2. But various instrumentations apply to different versions of the API. They are divided into the following sub-modules: + - `servlet-common` contains shared code for both `javax.servlet` and `jakarta.servlet` packages. - Version-specific modules contain the version-specific instrumentations and request/response accessor. @@ -21,7 +22,7 @@ They are divided into the following sub-modules: - `servlet-3.0` contains instrumentation for Servlet API versions `[3.0, 5)` - `servlet-5.0` contains instrumentation for Servlet API versions `[5,)` -## Implementation details +### Implementation details In order to fully understand how java servlet instrumentation work, let us first take a look at the following stacktrace from Spring PetClinic application. @@ -80,7 +81,8 @@ Each framework instrumentation can decide what is the best span name based on fr Of course, still adhering to OpenTelemetry [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md). -## Additional instrumentations +### Additional instrumentations + `HttpServletResponseInstrumentation` instruments `javax.servlet.http.HttpServletResponse.sendError` and `javax.servlet.http.HttpServletResponse.sendRedirect` methods to create new `INTERNAL` spans around their invocations. diff --git a/instrumentation/spring/README.md b/instrumentation/spring/README.md index cd43e6640267..58f39393d610 100644 --- a/instrumentation/spring/README.md +++ b/instrumentation/spring/README.md @@ -12,7 +12,7 @@ The [third section](#auto-instrumentation-using-spring-starters) with build on t In this guide we will be using a running example. In section one and two, we will create two spring web services using Spring Boot. We will then trace requests between these services using two different approaches. Finally, in section three we will explore tools documented in [opentelemetry-spring-boot-autoconfigure](./spring-boot-autoconfigure/README.md#features) which can improve this process. -# Settings +## Settings | System property | Type | Default | Description | |---|---|---|---| @@ -21,20 +21,21 @@ In this guide we will be using a running example. In section one and two, we wil | `otel.instrumentation.spring-webflux.experimental-span-attributes` | Boolean | `false` | Enable the capture of experimental span attributes for Spring WebFlux version 5.0. | | `otel.instrumentation.spring-webmvc.experimental-span-attributes` | Boolean | `false` | Enable the capture of experimental span attributes for Spring Web MVC 3.1. | -# Manual Instrumentation Guide +## Manual Instrumentation Guide -## Create two Spring Projects +### Create two Spring Projects Using the [spring project initializer](https://start.spring.io/), we will create two spring projects. Name one project `MainService` and the other `TimeService`. In this example `MainService` will be a client of `TimeService` and they will be dealing with time. Make sure to select maven, Spring Boot 2.3, Java, and add the spring-web dependency. After downloading the two projects include the OpenTelemetry dependencies and configuration listed below. -## Setup for Manual Instrumentation +### Setup for Manual Instrumentation Add the dependencies below to enable OpenTelemetry in `MainService` and `TimeService`. The Jaeger and LoggingExporter packages are recommended for exporting traces but are not required. As of May 2020, Jaeger, Zipkin, OTLP, and Logging exporters are supported by opentelemetry-java. Feel free to use whatever exporter you are most comfortable with. Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search.maven.org/search?q=g:io.opentelemetry). - - Minimum version: `1.1.0` -### Maven +- Minimum version: `1.1.0` + +#### Maven #### OpenTelemetry @@ -51,7 +52,7 @@ Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search. ``` -#### LoggingSpanExporter +##### LoggingSpanExporter ```xml @@ -61,7 +62,7 @@ Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search. ``` -#### Jaeger Exporter +##### Jaeger Exporter ```xml @@ -76,29 +77,29 @@ Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search. ``` -### Gradle +#### Gradle -#### OpenTelemetry +##### OpenTelemetry ```gradle implementation("io.opentelemetry:opentelemetry-api:OPENTELEMETRY_VERSION") implementation("io.opentelemetry:opentelemetry-sdk:OPENTELEMETRY_VERSION") ``` -#### LoggingExporter +##### LoggingExporter ```gradle implementation("io.opentelemetry:opentelemetry-exporter-logging:OPENTELEMETRY_VERSION") ``` -#### Jaeger Exporter +##### Jaeger Exporter ```gradle implementation("io.opentelemetry:opentelemetry-exporters-jaeger:OPENTELEMETRY_VERSION") compile "io.grpc:grpc-netty:1.30.2" ``` -### Tracer Configuration +#### Tracer Configuration To enable tracing in your OpenTelemetry project configure a Tracer Bean. This bean will be auto wired to controllers to create and propagate spans. This can be seen in the `Tracer otelTracer()` method below. If you plan to use a trace exporter remember to also include it in this configuration class. In section 3 we will use an annotation to set up this configuration. @@ -132,7 +133,6 @@ public class OtelConfig { } ``` - The file above configures an OpenTelemetry tracer and a span processor. The span processor builds a log exporter which will output spans to the console. Similarly, one could add another exporter, such as the `JaegerExporter`, to visualize traces on a different back-end. Similar to how the `LoggingExporter` is configured, a Jaeger configuration can be added to the `OtelConfig` class above. Sample configuration for a Jaeger Exporter: @@ -147,12 +147,12 @@ SpanProcessor jaegerProcessor = SimpleSpanProcessor OpenTelemetrySdk.getTracerManagement().addSpanProcessor(jaegerProcessor); ``` -### Project Background +#### Project Background Here we will create REST controllers for `MainService` and `TimeService`. `MainService` will send a GET request to `TimeService` to retrieve the current time. After this request is resolved, `MainService` then will append a message to time and return a string to the client. -## Manual Instrumentation with Java SDK +### Manual Instrumentation with Java SDK ### Add OpenTelemetry to MainService and TimeService @@ -165,61 +165,61 @@ Required dependencies and configurations for MainService and TimeService project 3. Ensure a Spring Boot main class was created by the Spring initializer -```java -@SpringBootApplication -public class MainServiceApplication { + ```java + @SpringBootApplication + public class MainServiceApplication { - public static void main(String[] args) { - SpringApplication.run(MainServiceApplication.class, args); + public static void main(String[] args) { + SpringApplication.run(MainServiceApplication.class, args); + } } -} -``` + ``` 4. Create a REST controller for MainService 5. Create a span to wrap MainServiceController.message() -```java -import org.springframework.beans.factory.annotation.Autowired; -import org.springframework.web.bind.annotation.GetMapping; -import org.springframework.web.bind.annotation.RequestMapping; -import org.springframework.web.bind.annotation.RestController; - -import io.opentelemetry.context.Scope; -import io.opentelemetry.api.trace.Span; -import io.opentelemetry.api.trace.Tracer; - -import HttpUtils; - -@RestController -@RequestMapping(value = "/message") -public class MainServiceController { - private static int requestCount = 1; - private static final String TIME_SERVICE_URL = "http://localhost:8081/time"; - - @Autowired - private Tracer tracer; - - @Autowired - private HttpUtils httpUtils; - - @GetMapping - public String message() { - Span span = tracer.spanBuilder("message").startSpan(); - - try (Scope scope = tracer.withSpan(span)) { - span.addEvent("Controller Entered"); - span.setAttribute("timeservicecontroller.request.count", requestCount++); - return "Time Service says: " + httpUtils.callEndpoint(TIME_SERVICE_URL); - } catch (Exception e) { - span.setAttribute("error", true); - return "ERROR: I can't tell the time"; - } finally { - span.addEvent("Exit Controller"); - span.end(); + ```java + import org.springframework.beans.factory.annotation.Autowired; + import org.springframework.web.bind.annotation.GetMapping; + import org.springframework.web.bind.annotation.RequestMapping; + import org.springframework.web.bind.annotation.RestController; + + import io.opentelemetry.context.Scope; + import io.opentelemetry.api.trace.Span; + import io.opentelemetry.api.trace.Tracer; + + import HttpUtils; + + @RestController + @RequestMapping(value = "/message") + public class MainServiceController { + private static int requestCount = 1; + private static final String TIME_SERVICE_URL = "http://localhost:8081/time"; + + @Autowired + private Tracer tracer; + + @Autowired + private HttpUtils httpUtils; + + @GetMapping + public String message() { + Span span = tracer.spanBuilder("message").startSpan(); + + try (Scope scope = tracer.withSpan(span)) { + span.addEvent("Controller Entered"); + span.setAttribute("timeservicecontroller.request.count", requestCount++); + return "Time Service says: " + httpUtils.callEndpoint(TIME_SERVICE_URL); + } catch (Exception e) { + span.setAttribute("error", true); + return "ERROR: I can't tell the time"; + } finally { + span.addEvent("Exit Controller"); + span.end(); + } } } -} -``` + ``` 6. Configure `HttpUtils.callEndpoint` to inject span context into request. This is key to propagate the trace to the TimeService @@ -275,26 +275,27 @@ public class HttpUtils { } } ``` + ### Instrumentation of TimeService 1. Ensure OpenTelemetry dependencies are included 2. Ensure an OpenTelemetry Tracer is configured 3. Ensure a Spring Boot main class was created by the Spring initializer -```java -import java.io.IOException; + ```java + import java.io.IOException; -import org.springframework.boot.SpringApplication; -import org.springframework.boot.autoconfigure.SpringBootApplication; + import org.springframework.boot.SpringApplication; + import org.springframework.boot.autoconfigure.SpringBootApplication; -@SpringBootApplication -public class TimeServiceApplication { + @SpringBootApplication + public class TimeServiceApplication { - public static void main(String[] args) { - SpringApplication.run(TimeServiceApplication.class, args); + public static void main(String[] args) { + SpringApplication.run(TimeServiceApplication.class, args); + } } -} -``` + ``` 4. Create a REST controller for TimeService 5. Start a span to wrap TimeServiceController.time() @@ -344,7 +345,7 @@ After running Jaeger locally, navigate to the url below. Make sure to refresh th Run MainService and TimeService from command line or using an IDE. The end point of interest for MainService is `http://localhost:8080/message` and `http://localhost:8081/time` for TimeService. Entering `localhost:8080/message` in a browser should call MainService and then TimeService, creating a trace. -***Note: The default port for the Apache Tomcat is 8080. On localhost both MainService and TimeService services will attempt to run on this port raising an error. To avoid this add `server.port=8081` to the resources/application.properties file. Ensure the port specified corresponds to port referenced by MainServiceController.TIME_SERVICE_URL. *** +***Note: The default port for the Apache Tomcat is 8080. On localhost both MainService and TimeService services will attempt to run on this port raising an error. To avoid this add `server.port=8081` to the resources/application.properties file. Ensure the port specified corresponds to port referenced by MainServiceController.TIME_SERVICE_URL.*** Congrats, we just created a distributed service with OpenTelemetry! @@ -601,8 +602,6 @@ To visualize this trace add a trace exporter to one or both of your applications To create a sample trace enter `localhost:8080/message` in a browser. This trace should include a span for MainService and a span for TimeService. - - ## Auto Instrumentation using Spring Starters In this tutorial we will create two SpringBoot applications (MainService and TimeService). We will @@ -616,7 +615,8 @@ Zipkin. Add the following dependencies to your build file. Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search.maven.org/search?q=g:io.opentelemetry). - - Minimum version: `1.1.0` + +- Minimum version: `1.1.0` #### Maven @@ -703,8 +703,6 @@ server.port=8081 Check out [OpenTelemetry Spring Boot AutoConfigure](spring-boot-autoconfigure/README.md) to learn more. - - ### TimeService Configure the main class in your `Time Service` project to match the file below. Here we use the Tracer bean provided by the OpenTelemetry starter to create an internal span and set some additional events and attributes. @@ -760,7 +758,6 @@ public class TimeServiceApplication { } ``` - ### Generating Trace - LoggingSpanExporter To generate a trace, run MainServiceApplication and TimeServiceApplication, and then send a request to `localhost:8080/message`. Shown below is the output of the default span exporter - [LoggingSpanExporter](https://github.com/open-telemetry/opentelemetry-java/tree/main/exporters/logging). @@ -828,7 +825,6 @@ status=Status{canonicalCode=OK, description=null}, name=WebMVCTracingFilter.doFi ``` - ### Exporter Starters To configure OpenTelemetry tracing with the OTLP, Zipkin, or Jaeger span exporters replace the OpenTelemetry Spring Starter dependency with one of the artifacts listed below: @@ -880,6 +876,7 @@ Add the following configurations to overwrite the default exporter values listed ### Sample Trace Zipkin To generate a trace using the zipkin exporter follow the steps below: + 1. Replace `opentelemetry-spring-boot-starter` with `opentelemetry-zipkin-spring-boot-starter` in your pom or gradle build file 2. Use the Zipkin [quick starter](https://zipkin.io/pages/quickstart) to download and run the zipkin executable jar - Ensure the zipkin endpoint matches the default value listed in your application properties @@ -887,7 +884,6 @@ To generate a trace using the zipkin exporter follow the steps below: 4. Use your favorite browser to send a request to `http://localhost:8080/message` 5. Navigate to `http://localhost:9411` to see your trace - Shown below is the sample trace generated by `MainService` and `TimeService` using the opentelemetry-zipkin-spring-boot-starter. ```json diff --git a/instrumentation/spring/spring-boot-autoconfigure/README.md b/instrumentation/spring/spring-boot-autoconfigure/README.md index 6b29157619fc..33d1cbbd7351 100644 --- a/instrumentation/spring/spring-boot-autoconfigure/README.md +++ b/instrumentation/spring/spring-boot-autoconfigure/README.md @@ -8,10 +8,11 @@ the [opentelemetry-spring-boot-starter](../starters/spring-boot-starter/README.m ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search.maven.org/search?q=g:io.opentelemetry). - - Minimum version: `1.17.0` + +- Minimum version: `1.17.0` For Maven, add to your `pom.xml` dependencies: @@ -60,10 +61,12 @@ implementation("io.opentelemetry:opentelemetry-exporters-otlp:OPENTELEMETRY_VERS The following dependencies are optional but are required to use the corresponding features. Replace `SPRING_VERSION` with the version of spring you're using. - - Minimum version: `3.1` + +- Minimum version: `3.1` Replace `SPRING_WEBFLUX_VERSION` with the version of spring-webflux you're using. - - Minimum version: `5.0` + +- Minimum version: `5.0` For Maven, add to your `pom.xml` dependencies: @@ -145,7 +148,6 @@ implementation("io.opentelemetry:opentelemetry-extension-annotations:OPENTELEMET #### OpenTelemetry Auto Configuration - #### OpenTelemetry Tracer Auto Configuration Provides a OpenTelemetry tracer bean (`io.opentelemetry.api.trace.Tracer`) if one does not exist in the application context of the spring project. This tracer bean will be used in all configurations listed below. Feel free to declare your own Opentelemetry tracer bean to overwrite this configuration. @@ -219,6 +221,7 @@ public class TracedClass { The traces below were exported using Zipkin. ##### Spring Web MVC - Server Span + ```json { "traceId":"0371febbbfa76b2e285a08b53a055d17", @@ -381,7 +384,6 @@ This package provides auto configurations for [OTLP](https://github.com/open-tel If an exporter is present in the classpath during runtime and a spring bean of the exporter is missing from the spring application context. An exporter bean is initialized and added to a simple span processor in the active tracer provider. Check out the implementation [here](./src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/OpenTelemetryAutoConfiguration.java). - #### Configuration Properties ##### Enabling/Disabling Features diff --git a/instrumentation/spring/spring-web-3.1/library/README.md b/instrumentation/spring/spring-web-3.1/library/README.md index 2576508c70f3..c2145fbc05a1 100644 --- a/instrumentation/spring/spring-web-3.1/library/README.md +++ b/instrumentation/spring/spring-web-3.1/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for Spring's RestTemplate. ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `SPRING_VERSION` with the version of spring you're using. `Minimum version: 3.1` diff --git a/instrumentation/spring/spring-webflux-5.0/library/README.md b/instrumentation/spring/spring-webflux-5.0/library/README.md index 710771a11113..c76a861a36f0 100644 --- a/instrumentation/spring/spring-webflux-5.0/library/README.md +++ b/instrumentation/spring/spring-webflux-5.0/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for Spring's `WebClient`. ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `SPRING_VERSION` with the version of spring you're using. `Minimum version: 5.0` diff --git a/instrumentation/spring/spring-webmvc-5.3/library/README.md b/instrumentation/spring/spring-webmvc-5.3/library/README.md index b28bc2d6f7f6..815940802285 100644 --- a/instrumentation/spring/spring-webmvc-5.3/library/README.md +++ b/instrumentation/spring/spring-webmvc-5.3/library/README.md @@ -4,10 +4,11 @@ Provides OpenTelemetry instrumentation for Spring WebMVC controllers. ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `SPRING_VERSION` with the version of spring you're using. - - `Minimum version: 5.3` + +- `Minimum version: 5.3` Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-spring-webmvc-5.3). diff --git a/instrumentation/spring/starters/jaeger-spring-boot-starter/README.md b/instrumentation/spring/starters/jaeger-spring-boot-starter/README.md index cf095b36c890..04e16f76d166 100644 --- a/instrumentation/spring/starters/jaeger-spring-boot-starter/README.md +++ b/instrumentation/spring/starters/jaeger-spring-boot-starter/README.md @@ -4,11 +4,11 @@ OpenTelemetry Jaeger Exporter Starter is a starter package that includes the ope ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search.maven.org/search?q=g:io.opentelemetry). - - Minimum version: `1.1.0` +- Minimum version: `1.1.0` #### Maven diff --git a/instrumentation/spring/starters/spring-boot-starter/README.md b/instrumentation/spring/starters/spring-boot-starter/README.md index 437cd8510706..aac33afe3d71 100644 --- a/instrumentation/spring/starters/spring-boot-starter/README.md +++ b/instrumentation/spring/starters/spring-boot-starter/README.md @@ -6,10 +6,11 @@ This version is compatible with Spring Boot 2.0. ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search.maven.org/search?q=g:io.opentelemetry). - - Minimum version: `1.1.0` + +- Minimum version: `1.1.0` ### Maven diff --git a/instrumentation/spring/starters/zipkin-spring-boot-starter/README.md b/instrumentation/spring/starters/zipkin-spring-boot-starter/README.md index 13bc98ede5aa..7286cdebaee6 100644 --- a/instrumentation/spring/starters/zipkin-spring-boot-starter/README.md +++ b/instrumentation/spring/starters/zipkin-spring-boot-starter/README.md @@ -6,11 +6,11 @@ OpenTelemetry Zipkin Exporter Starter is a starter package that includes the ope ## Quickstart -### Add these dependencies to your project. +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://search.maven.org/search?q=g:io.opentelemetry). - - Minimum version: `1.1.0` +* Minimum version: `1.1.0` #### Maven diff --git a/instrumentation/tomcat/README.md b/instrumentation/tomcat/README.md index e8059b826156..1b7edec2f80f 100644 --- a/instrumentation/tomcat/README.md +++ b/instrumentation/tomcat/README.md @@ -1,6 +1,7 @@ # Instrumentation for Tomcat request handlers Tomcat support is divided into the following sub-modules: + - `tomcat-common:javaagent` contains common type instrumentation, advice helper classes and abstract tracer used by the `javaagent` modules of all supported Tomcat versions - `tomcat-7.0:javaagent` applies Tomcat request handler instrumentation for versions `[7, 10)` diff --git a/instrumentation/vibur-dbcp-11.0/library/README.md b/instrumentation/vibur-dbcp-11.0/library/README.md index 2ea37c8339ec..f911e0e39e87 100644 --- a/instrumentation/vibur-dbcp-11.0/library/README.md +++ b/instrumentation/vibur-dbcp-11.0/library/README.md @@ -4,7 +4,7 @@ Provides OpenTelemetry instrumentation for [Vibur DBCP](https://www.vibur.org/). ## Quickstart -### Add these dependencies to your project: +### Add these dependencies to your project Replace `OPENTELEMETRY_VERSION` with the [latest release](https://search.maven.org/search?q=g:io.opentelemetry.instrumentation%20AND%20a:opentelemetry-vibur-dbcp-11.0). diff --git a/smoke-tests/README.md b/smoke-tests/README.md index ffcc8ac26867..9d4c2426efb1 100644 --- a/smoke-tests/README.md +++ b/smoke-tests/README.md @@ -1,4 +1,5 @@ # Smoke Tests + Assert that various applications will start up with the JavaAgent without any obvious ill effects. Each subproject underneath `smoke-tests` produces one or more docker images containing some application diff --git a/smoke-tests/images/play/README.md b/smoke-tests/images/play/README.md index 60f0619abe16..1b65297ef83d 100644 --- a/smoke-tests/images/play/README.md +++ b/smoke-tests/images/play/README.md @@ -1,3 +1,4 @@ # Play framework smoke test + Play application used by smoke tests of OpenTelemetry java agent. Builds and publishes Docker image containing a trivial Play application. diff --git a/smoke-tests/images/servlet/README.md b/smoke-tests/images/servlet/README.md index 8c0dfbd4b27d..76c9dceca93d 100644 --- a/smoke-tests/images/servlet/README.md +++ b/smoke-tests/images/servlet/README.md @@ -1,4 +1,5 @@ # Smoke Test Environment Matrix + This project builds docker images containing a simple test web application deployed to various application servers or servlet containers. For each server several relevant versions are chosen. In addition we build separate images for several support major java versions. diff --git a/smoke-tests/images/spring-boot/README.md b/smoke-tests/images/spring-boot/README.md index ee88dffdc519..2b97bb892c55 100644 --- a/smoke-tests/images/spring-boot/README.md +++ b/smoke-tests/images/spring-boot/README.md @@ -1,3 +1,4 @@ # Spring Boot smoke test + Spring Boot application used by smoke tests of OpenTelemetry java agent. Builds and publishes Docker image containing a trivial Spring MVC application. diff --git a/testing-common/src/misc/README.md b/testing-common/src/misc/README.md index 105a7b244c5d..e1f3a0a355c8 100644 --- a/testing-common/src/misc/README.md +++ b/testing-common/src/misc/README.md @@ -1,5 +1,9 @@ -testing-keystore.p12 generated with +# Miscellaneous +testing-keystore.p12 generated with: + +``` keytool -genkeypair -keyalg RSA -keysize 2048 -storetype PKCS12 -keystore testing-keystore.p12 -validity 3650 -dname "CN=localhost" -ext "SAN=dns:localhost,ip:127.0.0.1" password = testing +```