diff --git a/.github/config/.markdownlint-cli2.yaml b/.github/config/.markdownlint-cli2.yaml new file mode 100644 index 000000000000..3b70078f11d4 --- /dev/null +++ b/.github/config/.markdownlint-cli2.yaml @@ -0,0 +1,19 @@ +# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md +# and https://github.com/DavidAnson/markdownlint-cli2 + +config: + ul-style: false + line-length: false + no-duplicate-heading: + siblings_only: true + ol-prefix: + style: ordered + no-inline-html: false + fenced-code-language: false + no-trailing-punctuation: + punctuation: ".,;:" # allowing exclamation points and question marks at end of sentences + +ignores: + - "**/build/**" + - "CHANGELOG.md" + - "licenses/licenses.md" diff --git a/.github/config/markdownlint.yml b/.github/config/markdownlint.yml deleted file mode 100644 index 61e39a0a22fb..000000000000 --- a/.github/config/markdownlint.yml +++ /dev/null @@ -1,14 +0,0 @@ -# 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/.github/repository-settings.md b/.github/repository-settings.md index ae3da8c10381..b04c3138edef 100644 --- a/.github/repository-settings.md +++ b/.github/repository-settings.md @@ -14,7 +14,7 @@ private admin repo. - `GRADLE_PUBLISH_KEY` - owned by [@trask](https://github.com/trask) - `GRADLE_PUBLISH_SECRET` - owned by [@trask](https://github.com/trask) - `NVD_API_KEY` - stored in OpenTelemetry-Java 1Password - - Generated at https://nvd.nist.gov/developers/request-an-api-key + - Generated at - Key is associated with [@trask](https://github.com/trask)'s gmail address - `SONATYPE_KEY` - owned by [@trask](https://github.com/trask) - `SONATYPE_USER` - owned by [@trask](https://github.com/trask) diff --git a/.github/workflows/reusable-markdown-lint-check.yml b/.github/workflows/reusable-markdown-lint-check.yml index a0760e84bbd5..7c60ede27731 100644 --- a/.github/workflows/reusable-markdown-lint-check.yml +++ b/.github/workflows/reusable-markdown-lint-check.yml @@ -14,4 +14,4 @@ jobs: - name: Run markdownlint run: | - npx markdownlint-cli@0.46.0 -c .github/config/markdownlint.yml -p .gitignore **/*.md -i licenses/licenses.md + npx markdownlint-cli2@0.17.1 --config .github/config/.markdownlint-cli2.yaml "**/*.md" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b2f213ad6df..5b46065e805c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,6 @@ 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. - ## Breaking Changes When your PR introduces a breaking change: diff --git a/docs/contributing/documenting-instrumentation.md b/docs/contributing/documenting-instrumentation.md index 0de5351467fe..0dc156faf118 100644 --- a/docs/contributing/documenting-instrumentation.md +++ b/docs/contributing/documenting-instrumentation.md @@ -69,11 +69,9 @@ Every javaagent instrumentation module should have a README.md file in the javaa | `property.name` | Type | Default | Description | ``` - **Note:** At some point we will likely automate the generation of this javaagent README.md file using the metadata.yaml file described below. - ## Metadata.yaml Files Each instrumentation should have a `metadata.yaml` file in the root of the instrumentation directory @@ -168,7 +166,6 @@ Some notes when writing descriptions: * Example: "This instrumentation enriches HTTP server spans with route information, and enables controller spans for Apache CXF JAX-WS web services (controller spans are disabled by default)." - ### Semantic Conventions If the instrumentation adheres to one or more specific semantic conventions, include a @@ -228,12 +225,10 @@ Each configuration should include: * `type`: The data type of the configuration value. Supported types are: `boolean`, `string`, `list`, and `map`. * `default`: The default value for the configuration. - If a configuration enables experimental attributes, list them, for example: > Enables experimental span attributes `couchbase.operation_id` and `couchbase.local.address`. - ### Classification (optional) If an instrumentation module does not specify a `classification`, it is assumed to be `library`. @@ -251,7 +246,6 @@ The primary way this `classification` is used is to group and filter instrumenta utility in tooling and documentation. If you are unsure which classification to use, you can omit this field, and it will default to `library`. - ### Disabled by Default (optional) If an instrumentation is disabled by default, set `disabled_by_default: true`. This indicates that diff --git a/docs/contributing/running-tests.md b/docs/contributing/running-tests.md index e2764fceb9d6..dcf5259128e4 100644 --- a/docs/contributing/running-tests.md +++ b/docs/contributing/running-tests.md @@ -100,13 +100,14 @@ old containers, images and volumes using `docker system prune --volumes`. For some container environments, such as rootless Podman or a remotely hosted Docker, testcontainers may need additional configuration to successfully run the tests. The following environment variables can be used for configuration: + - `TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE` - The location of the Docker socket on the host. Default is `/var/run/docker.sock` - `TESTCONTAINERS_HOST_OVERRIDE` - The hostname used for container-to-container communication. Default Docker is `localhost`, but rootless Podman uses `host.containers.internal` -# Troubleshooting CI Test Failures +## Troubleshooting CI Test Failures See [Troubleshooting CI Test Failures](../../CONTRIBUTING.md#troubleshooting-pr-build-failures) for common issues and solutions. -# Debugging +## Debugging For information on debugging tests or instrumentation, see [Debugging](debugging.md). diff --git a/docs/contributing/style-guideline.md b/docs/contributing/style-guideline.md index cd4cb7459fb1..43cc036e06cb 100644 --- a/docs/contributing/style-guideline.md +++ b/docs/contributing/style-guideline.md @@ -102,7 +102,7 @@ Method parameters and local variables should never be declared `final`. ## `@Nullable` annotation usage -**Note: this section is aspirational, as opposed to a reflection of the current codebase** +**Note: this section is aspirational, as opposed to a reflection of the current codebase.** All parameters and fields which can be `null` should be annotated with `@Nullable` (specifically `javax.annotation.Nullable`, which is included by the diff --git a/docs/contributing/writing-instrumentation-module.md b/docs/contributing/writing-instrumentation-module.md index ffbf3dbfc2a5..42767e7c9e9c 100644 --- a/docs/contributing/writing-instrumentation-module.md +++ b/docs/contributing/writing-instrumentation-module.md @@ -407,6 +407,7 @@ In order to preserve compatibility with both instrumentation strategies, we have from the advice method annotations. We have three sets of instrumentation modules: + - "inlined only": only compatible with "inlined", `isIndyModule` returns `false`. - "indy compatible": compatible with both "indy" and "inlined", do not override `isIndyModule`, advices are modified with `AdviceTransformer` to be made "indy native" or "inlined" at runtime. - "indy native": only compatible with "indy" `isIndyModule` returns `true`. diff --git a/docs/contributing/writing-instrumentation.md b/docs/contributing/writing-instrumentation.md index 8f17ab0b7c72..bbc40047afba 100644 --- a/docs/contributing/writing-instrumentation.md +++ b/docs/contributing/writing-instrumentation.md @@ -282,7 +282,6 @@ You can use the `@RegisterExtension` annotation to make sure that the instrument picked up by JUnit. Then, return the same extension instance in the `testing()` method implementation so that it's used in all test scenarios implemented in the abstract class. - ## Writing Java agent instrumentation Now that you have working and tested library instrumentation, implement the javaagent diff --git a/instrumentation/aws-sdk/aws-sdk-2.2/library/README.md b/instrumentation/aws-sdk/aws-sdk-2.2/library/README.md index 0d909888b7b8..660190a311fc 100644 --- a/instrumentation/aws-sdk/aws-sdk-2.2/library/README.md +++ b/instrumentation/aws-sdk/aws-sdk-2.2/library/README.md @@ -18,11 +18,13 @@ DynamoDbClient client = DynamoDbClient.builder() ``` For SQS an additional step is needed + ```java SqsClientBuilder sqsClientBuilder = SqsClient.builder(); ... SqsClient sqsClient = telemetry.wrap(sqsClientBuilder.build()); ``` + ```java SqsAsyncClientBuilder sqsAsyncClientBuilder = SqsAsyncClient.builder(); ... diff --git a/instrumentation/graphql-java/README.md b/instrumentation/graphql-java/README.md index ba7bb42d6712..e6080d8b8ffe 100644 --- a/instrumentation/graphql-java/README.md +++ b/instrumentation/graphql-java/README.md @@ -1,4 +1,6 @@ -# Settings for the GraphQL instrumentation +# GraphQL Instrumentation + +## Settings for the GraphQL instrumentation | System property | Type | Default | Description | |------------------------------------------------------------------------|---------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -6,7 +8,7 @@ | `otel.instrumentation.graphql.add-operation-name-to-span-name.enabled` | Boolean | `false` | Whether GraphQL operation name is added to the span name.

**WARNING**: GraphQL operation name is provided by the client and can have high cardinality. Use only when the server is not exposed to malicious clients. | | `otel.instrumentation.graphql.capture-query` | Boolean | `true` | Whether to capture the query in `graphql.document` span attribute. | -# Settings for the GraphQL 20 instrumentation +## Settings for the GraphQL 20 instrumentation | System property | Type | Default | Description | |-------------------------------------------------------------|---------|---------|-----------------------------------------------------------------------------------------------------------------------------------| diff --git a/instrumentation/jmx-metrics/README.md b/instrumentation/jmx-metrics/README.md index 71b6b879d914..0c4d67e97c03 100644 --- a/instrumentation/jmx-metrics/README.md +++ b/instrumentation/jmx-metrics/README.md @@ -273,18 +273,22 @@ For other values of `stateName`, we have: - `tomcat.connector.status` value = `1`, attributes `port` = `8080` and `tomcat.connector.state` = `degraded` Each state key can be mapped to one or more values of the MBean attribute using: + - a string literal or a string array - a `*` character to provide default option and avoid enumerating all values, this value must be quoted in YAML Exactly one `*` value must be present in the mapping to ensure all possible values of the MBean attribute can be mapped to a state key. The default value indicated by `*` does not require a dedicated state key. For example, if we want to have `tomcat.connector.state` metric attribute with values `on` or `off`, we can use: + ```yaml tomcat.connector.state: on: STARTED off: [STOPPED,FAILED,'*'] ``` + In the particular case where only two values are defined, we can simplify further by explicitly defining one state and rely on default for the other. + ```yaml tomcat.connector.state: on: STARTED @@ -301,7 +305,6 @@ For example, with JVM memory, the `java.lang:name=*,type=MemoryPool` MBeans have However, in the semantic conventions the metric attribute `jvm.memory.type` should be lower-cased to fit the `jvm.memory.used` definition, in this case we can apply the `lowercase` metric attribute transformation as follows: - ```yaml --- rules: @@ -312,7 +315,7 @@ rules: metric: jvm.memory.used unit: By metricAttribute: - jvm.memory.pool.name : param(name) + jvm.memory.pool.name: param(name) jvm.memory.type: lowercase(beanattr(Type)) ``` @@ -337,6 +340,7 @@ Currently available unit conversions: | ns | s | Example of defining unit conversion in yaml file: + ```yaml rules: - beans: @@ -350,6 +354,7 @@ rules: unit: s desc: The longest request processing time ``` + `sourceUnit` can also be defined on rule level (see [Making shortcuts](#making-shortcuts)) ### Filtering negative values @@ -396,11 +401,13 @@ where the `name` parameter in the MBean name is NOT mapped to a metric attribute ``` When two or more MBean parameters are used, it is also possible to perform a partial aggregation: + - parameters not mapped as metric attributes are discarded - parameters mapped as metric attributes with `param()` are preserved - values are aggregated with mapped metric attributes The applied aggregation depends on the metric type: + - `counter` or `updowncounter`: sum aggregation - `gauge`: last-value aggregation diff --git a/instrumentation/jmx-metrics/library/jetty.md b/instrumentation/jmx-metrics/library/jetty.md index a0b9c5a9bd30..bad831ac0f06 100644 --- a/instrumentation/jmx-metrics/library/jetty.md +++ b/instrumentation/jmx-metrics/library/jetty.md @@ -3,6 +3,7 @@ Here is the list of metrics based on MBeans exposed by [Jetty](https://jetty.org/). The metrics captured and their respective attributes depend on the Jetty version: + - [Jetty 12 and later](#jetty-12-and-later) - [Jetty 9 to 11](#jetty-9-to-11) diff --git a/instrumentation/logback/logback-appender-1.0/library/README.md b/instrumentation/logback/logback-appender-1.0/library/README.md index 8f91c76f624a..33206464e2dc 100644 --- a/instrumentation/logback/logback-appender-1.0/library/README.md +++ b/instrumentation/logback/logback-appender-1.0/library/README.md @@ -107,5 +107,4 @@ The available settings are: | `captureEventName` | Boolean | `false` | Enable moving the `event.name` attribute (captured by one of the other mechanisms of capturing attributes) to the log event name. | | `numLogsCapturedBeforeOtelInstall` | Integer | 1000 | Log telemetry is emitted after the initialization of the OpenTelemetry Logback appender with an OpenTelemetry object. This setting allows you to modify the size of the cache used to replay the first logs. thread.id attribute is not captured. | - [source code attributes]: https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#source-code-attributes diff --git a/instrumentation/methods/README.md b/instrumentation/methods/README.md index a40b41c48892..23bf3ae80124 100644 --- a/instrumentation/methods/README.md +++ b/instrumentation/methods/README.md @@ -1,4 +1,6 @@ -# Settings for the methods instrumentation +# Methods Instrumentation + +## Settings for the methods instrumentation Provides a flexible way to capture telemetry at the method level in JVM applications. By weaving instrumentation into targeted methods at runtime based on the "otel.instrumentation.methods.include" @@ -11,7 +13,7 @@ occurrences. The resulting data is automatically translated into OpenTelemetry t [cs]: https://opentelemetry.io/docs/zero-code/java/agent/annotations/#creating-spans-around-methods-with-otelinstrumentationmethodsinclude -# Declarative Configuration Example +## Declarative Configuration Example In addition to configuring method instrumentation via system properties, you can use declarative configuration files to specify which methods to trace. This approach allows for more flexible and diff --git a/instrumentation/oshi/README.md b/instrumentation/oshi/README.md index 490f23ca650b..223bd981ba42 100644 --- a/instrumentation/oshi/README.md +++ b/instrumentation/oshi/README.md @@ -1,9 +1,11 @@ -# Settings for the OSHI instrumentation +# OSHI Instrumentation + +## Settings for the OSHI instrumentation | System property | Type | Default | Description | |-----------------------------------------------------------| ------- | ------- |--------------------------| | `otel.instrumentation.oshi.experimental-metrics.enabled` | Boolean | `false` | Enable the OSHI metrics. | -# Using OSHI with OpenTelemetry Java agent +## Using OSHI with OpenTelemetry Java agent -Download oshi-core jar from https://central.sonatype.com/artifact/com.github.oshi/oshi-core and place it on the class path. OpenTelemetry Java agent uses system class loader to load classes from the oshi-core jar that are used for the metrics. +Download oshi-core jar from and place it on the class path. OpenTelemetry Java agent uses system class loader to load classes from the oshi-core jar that are used for the metrics. diff --git a/instrumentation/runtime-telemetry/runtime-telemetry-java17/library/README.md b/instrumentation/runtime-telemetry/runtime-telemetry-java17/library/README.md index 5eed38ef70be..382475411c6c 100644 --- a/instrumentation/runtime-telemetry/runtime-telemetry-java17/library/README.md +++ b/instrumentation/runtime-telemetry/runtime-telemetry-java17/library/README.md @@ -1,3 +1,5 @@ +# Runtime Telemetry Java 17 + The main entry point is the `RuntimeMetrics` class in the package `io.opentelemetry.instrumentation.runtimemetrics.java17`: ```java