In this video, you’ll see how to capture trace data using the AWS Distro for OpenTelemetry.
With this solution, you can auto-instrument trace sending from Java web applications to AWS X-Ray
so that you can analyze trace data and debug errors.
AWS Distro for OpenTelemetry is the secure, production-ready AWS-supported distribution of the open-source OpenTelemetry project.
It provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your applications.
To get started, let’s take a quick look at the technical documentation for AWS Distro for OpenTelemetry, which is available on GitHub.
Here, you can learn about the solution’s features and download the AWS Distro for OpenTelemetry Collector.
Using the AWS Distro for OpenTelemetry Collector, you can instrument your applications just once
and send correlated metrics and traces to one or multiple monitoring solutions of your choice, including AWS X-Ray.
Let's navigate to AWS X-Ray now.
With AWS X-Ray, you can use traces collected from your AWS resources and managed services
to pinpoint and debug any issues, identify bottlenecks, and more.
To demonstrate the simple, automated, out-of-the-box experience of sending traces to X-Ray,
we’ll use a publicly available sample Java application called Pet Clinic.
You can either use the prebuilt package or build it from the source code yourself.
Alternatively, you can use any Java application package that you have ready.
Now, let’s start the process of configuring the sample application in our environment.
First, we’ll run the MySQL database for our sample application as a docker container.
We’ll also run the AWS Otel Collector as a docker container,
but first we need to provide the container with access to AWS X-Ray.
In Identity and Access Management (IAM), a user with full access to AWS X-Ray already exists,
which we can use to give the container access.
The Security credentials tab contains the access and secret key necessary for the next step.
Now, let's return to our development environment.
We’ll export the user’s access key and secret access key,
along with the AWS region, as environment variables so we can use the keys safely.
Now that we’ve set the AWS credentials, let's start the AWS Otel Collector docker container.
Please note that for the purposes of this demonstration, running this docker container is a prerequisite.
With our AWS Otel Collector container running,
let’s download the AWS-provided OpenTelemetry Java auto-instrumentation agent.
This agent will send traces to the X-Ray service for the AWS account we specified
by using the keys and region as command line arguments.
Now let’s download our sample Java application from GitHub.
Now that setup is complete, let's use the Java auto-instrumentation agent to capture
traces for the application while it is running and send them to the collector, which in turn
transmits them to AWS X-Ray for analysis.
You can access the web application using the link in the upper right corner.
By default, the link is private and not publicly accessible.
You can change these settings in the EC2 Management Console.
In this case, we have already opened port 8080 to all inbound traffic on our EC2 instance's security group.
Let’s return to our development environment and open the application.
To generate and send traces to AWS X-Ray, let’s simulate some user interactions.
In this case, we want our application to access the database, so we’ll look up a pet owner.
We’ll select the owner’s name to query the database for their information.
We have now simulated a few different traces, so let's go back to AWS X-Ray and take a look.
We can now see a list of trace URLs that our user interactions generated.
Let's view the trace we generated when we queried the owner information page.
The trace details show that the client sent our application one request,
which in turn sent three requests to the database.
All four requests were successful.
Let's take a closer look at one of the requests sent to the database.
Here, you can see general information about the trace's subsegment, including its ID, parent ID,
when it started and ended, the duration, and if there were any errors or faults.
This tab provides details about the AWS resources used by this subsegment.
Here, you can add annotations to use when recording data for grouping traces in the console,
or when calling the GetTraceSummaries API.
You can use metadata to record additional data that you want to store in the trace but don't need for searching traces.
If an exception occurs while your application is serving an instrumented request,
the X-Ray SDK records the details, including the stack trace, if available.
The SQL tab shows details about the queried database, including the sanitized query,
the URL, and the user who ran the query.
Now let's close this subsegment and go back to our development environment to generate some error traces by shutting down our MySQL container.
The Java application process is running in the foreground, so let's use a new terminal.
To find the container's ID, we’ll list the running containers.
Now let's copy our MySQL container ID and stop the container.
Let's list our running containers once more to ensure our container has been stopped.
Our MySQL container did not show up on the list, confirming it has been stopped.
Now let's go back to our application and simulate some more user interactions.
Let’s query for a pet owner’s details again.
Our query has errored out.
Let's go to AWS X-Ray and check our traces to find out why.
The URL ends with an equals sign, which indicates that the application failed to query the pet owner's details.
Let's look at the traces.
The trace details show that the client experienced a 500 error when querying the database by trying to access the owner details page.
Let's look at the subsegment for this action.
Notice there isn’t a SQL tab.
This is because this subsegment errored out trying to connect to the database, so a SQL query was never made.
Looking at the first line of this error trace, we can see that our Java application
was unable to acquire a JDBC Connection or was unable to connect to the database.
You’ve just seen how to capture trace data using the AWS Distro for OpenTelemetry.
Thanks for watching. Now it's your turn to try.