Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/aws-observability/aws-otel-java-instrumentation

AWS Distro for OpenTelemetry Java Instrumentation Library
https://github.com/aws-observability/aws-otel-java-instrumentation

observability opensource opentelemetry opentelemetry-api

Last synced: 4 days ago
JSON representation

AWS Distro for OpenTelemetry Java Instrumentation Library

Awesome Lists containing this project

README 

        
# AWS Distro for OpenTelemetry - Instrumentation for Java



## Introduction



This project is a redistribution of the [OpenTelemetry Agent for Java](https://github.com/open-telemetry/opentelemetry-java-instrumentation),

preconfigured for use with AWS services. Please check out that project too to get a better

understanding of the underlying internals. You won't see much code in this repository since we only

apply some small configuration changes, and our OpenTelemetry friends takes care of the rest.



We provided a Java agent JAR that can be attached to any Java 8+ application and dynamically injects 

bytecode to capture telemetry from a number of popular libraries and frameworks. The telemetry data 

can be exported in a variety of formats. In addition, the agent and exporter can be configured via 

command line arguments or environment variables. The net result is the ability to gather telemetry

data from a Java application without any code changes.



Note: There are 2.x releases and 1.x releases. The 2.0 release included significant breaking changes from [OpenTelemetry Agent for Java](https://github.com/open-telemetry/opentelemetry-java-instrumentation), 

the details of which can be found in the [release notes](https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases). 

It is recommended to use the latest 2.x release which will have the latest features and improvements. 

1.x will receive security patches for a limited time and will not include other bug fixes and enhancements.



## Getting Started



Check out the [getting started documentation](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr).



## Supported Java libraries and frameworks



For the complete list of supported frameworks, please refer to the [OpenTelemetry for Java documentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/master/README.md#supported-java-libraries-and-frameworks).



## How it works



The [OpenTelemetry Java SDK](https://github.com/open-telemetry/opentelemetry-java) provides knobs

for configuring aspects using Java [SPI](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html).

This configuration includes being able to reconfigure the [IdsGenerator](https://github.com/open-telemetry/opentelemetry-java-contrib/blob/ed5c91ea2ea0cfd36b77c1f871c540ceba1c057b/aws-xray/src/main/java/io/opentelemetry/contrib/awsxray/AwsXrayIdGenerator.java)

which we need to support X-Ray compatible trace IDs. Because the SDK uses SPI, it is sufficient for

the custom implementation to be on the classpath to be recognized. The AWS distribution of the

OpenTelemetry Java Agent repackages the upstream agent by simply adding our SPI implementation for

reconfiguring the ID generator. In addition, it includes [AWS resource providers](https://github.com/open-telemetry/opentelemetry-java-contrib/tree/main/aws-resources/src/main/java/io/opentelemetry/contrib/aws/resource) 

by default, and it sets a system property to configure the agent to use multiple trace ID propagators, 

defaulting to maximum interoperability.



Other than that, the distribution is identical to the upstream agent and all configuration can be

used as is.



## Standardized Sample Applications 



In addition to the sample apps in this repository, there are also a set of [standardized sample applications](https://github.com/aws-observability/aws-otel-community/tree/master/sample-apps) that can be used. You can find the standardized Java sample app [here](https://github.com/aws-observability/aws-otel-community/tree/master/sample-apps/java-sample-app).



## Support



Please note that as per policy, we're providing support via GitHub on a best effort basis. However, if you have AWS Enterprise Support you can create a ticket and we will provide direct support within the respective SLAs.



## Security issue notifications



If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.



## Checksum Verification



Artifacts released will include a `.sha256` file for checksum verification starting from v1.32.6

To verify, run the command `shasum -a 256 -c .sha256` 

It should return the output `: OK` if the validation is successful