AWS App Runner will no longer be open to new customers starting April 30, 2026. If you would like to use App Runner, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see [AWS App Runner availability change](https://docs.aws.amazon.com/apprunner/latest/dg/apprunner-availability-change.html).
# Tracing for your App Runner application with X-Ray
AWS X-Ray is a service that collects data about requests that your application serves, and provides tools you can use to view, filter, and gain insights into that data to identify issues and opportunities for optimization. For any traced request to your application, you can see detailed information not only about the request and response, but also about calls that your application makes to downstream AWS resources, microservices, databases and HTTP web APIs.
X-Ray uses trace data from the AWS resources that power your cloud applications to generate a detailed service graph. The service graph shows the client, your front-end service, and backend services that your front-end service calls to process requests and persist data. Use the service graph to identify bottlenecks, latency spikes, and other issues to solve to improve the performance of your applications.
For more information about X-Ray, see the [AWS X-Ray Developer Guide](https://docs.aws.amazon.com/xray/latest/devguide/).
![\[An example of an X-Ray service map for an App Runner service\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/xray-example.png)
## Instrument your application for tracing
Instrument your App Runner service application for tracing using [OpenTelemetry](https://github.com/open-telemetry), a portable telemetry specification. At this time, App Runner supports the [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) (ADOT), an OpenTelemetry implementation that collects and presents telemetry information using AWS services. X-Ray implements the tracing component.
Depending on the specific ADOT SDK that you use in your application, ADOT supports up to two instrumentation approaches: *automatic* and *manual*. For more information about instrumentation with your SDK, see the [ADOT documentation](https://aws-otel.github.io/docs/introduction), and choose your SDK on the navigation pane.
### Runtime setup
The following are the general runtime setup instructions to instrument your App Runner service application for tracing.
**To setup tracing for your runtime**
1. Follow the instructions provided for your runtime in [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) (ADOT), to instrument your application.
1. Install the required `OTEL` dependencies in the `build` section of the `apprunner.yaml` file if you are using the source code repository or in the Dockerfile if you are using a container image.
1. Setup your environment variables in the `apprunner.yaml` file if you are using the source code repository or in the Dockerfile if you are using a container image.
**Example Environment variables**
**Note**
The following example lists the important environment variables to add to the `apprunner.yaml` file. Add these environment variables to your Dockerfile if you are using a container image. However, each runtime can have their own idiosyncrasies and you may need to add more environment variables to the following list. For more information on your runtime specific instructions and examples on how to setup your application for your runtime, see [AWS Distro for OpenTelemetry](https://aws-otel.github.io/docs/introduction) and go to your runtime, under *Getting Started*.
```
env:
- name: OTEL_PROPAGATORS
value: xray
- name: OTEL_METRICS_EXPORTER
value: none
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: http://localhost:4317
- name: OTEL_RESOURCE_ATTRIBUTES
value: 'service.name=example_app'
```
**Note**
`OTEL_METRICS_EXPORTER=none` is an important environment variable for App Runner since the App Runner Otel collector doesn't accept metrics logging. It only accepts metrics tracing.
### Runtime setup example
The following example demonstrates auto-instrumenting your application with the [ADOT Python SDK](https://aws-otel.github.io/docs/getting-started/python-sdk). The SDK automatically produces spans with telemetry data describing the values used by the Python frameworks in your application without adding a single line of Python code. You need to add or modify just a few lines in two source files.
First, add some dependencies, as shown in the following example.
**Example requirements.txt**
```
opentelemetry-distro[otlp]>=0.24b0
opentelemetry-sdk-extension-aws~=2.0
opentelemetry-propagator-aws-xray~=1.0
```
Then, instrument your application. The way to do it depends on your service source—source image or source code.
------
#### [ Source image ]
When your service source is an image, you can directly instrument the Dockerfile that controls building your container image and running the application in the image. The following example shows an instrumented Dockerfile for a Python application. Instrumentation additions are emphasized in bold.
**Example Dockerfile**
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install python3.7 -y && curl -O https://bootstrap.pypa.io/get-pip.py && python3 get-pip.py && yum update -y
COPY . /app
WORKDIR /app
RUN pip3 install -r requirements.txt
RUN opentelemetry-bootstrap --action=install
ENV OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=urllib3
ENV OTEL_METRICS_EXPORTER=none
ENV OTEL_RESOURCE_ATTRIBUTES='service.name=example_app'
CMD OTEL_PROPAGATORS=xray OTEL_PYTHON_ID_GENERATOR=xray opentelemetry-instrument python3 app.py
EXPOSE 8080
```
------
#### [ Source code repository ]
When your service source is a repository containing your application source, you indirectly instrument your image using App Runner configuration file settings. These settings control the Dockerfile that App Runner generates and uses to build the image for your application. The following example shows an instrumented App Runner configuration file for a Python application. Instrumentation additions are emphasized in bold.
**Example apprunner.yaml**
```
version: 1.0
runtime: python3
build:
commands:
build:
- pip install -r requirements.txt
- opentelemetry-bootstrap --action=install
run:
command: opentelemetry-instrument python app.py
network:
port: 8080
env:
- name: OTEL_PROPAGATORS
value: xray
- name: OTEL_METRICS_EXPORTER
value: none
- name: OTEL_PYTHON_ID_GENERATOR
value: xray
- name: OTEL_PYTHON_DISABLED_INSTRUMENTATIONS
value: urllib3
- name: OTEL_RESOURCE_ATTRIBUTES
value: 'service.name=example_app'
```
------
## Add X-Ray permissions to your App Runner service instance role
To use X-Ray tracing with your App Runner service, you have to provide the service's instances with permissions to interact with the X-Ray service. You do this by associating an instance role with your service and adding a managed policy with X-Ray permissions. For more information about an App Runner instance role, see [Instance role](security_iam_service-with-iam.md#security_iam_service-with-iam-roles-service.instance). Add the `AWSXRayDaemonWriteAccess` managed policy to your instance role and assign it to your service during creation.
## Enable X-Ray tracing for your App Runner service
When you [create a service](manage-create.md), App Runner disables tracing by default. You can enable X-Ray tracing for your service as part of configuring observability. For more information, see [Manage observability](manage-configure-observability.md#manage-configure-observability.manage).
If you use the App Runner API or the AWS CLI, the [TraceConfiguration](https://docs.aws.amazon.com/apprunner/latest/api/API_TraceConfiguration.html) object within the [ObservabilityConfiguration](https://docs.aws.amazon.com/apprunner/latest/api/API_ObservabilityConfiguration.html) resource object contains tracing settings. To keep tracing disabled, don't specify a `TraceConfiguration` object.
In both the console and API cases, be sure to associate your instance role discussed in the previous section with your App Runner service.
## View X-Ray tracing data for your App Runner service
On the **Observability** tab of the [service dashboard page](console.md#console.dashboard) in the App Runner console, choose **View service map** to navigate to the Amazon CloudWatch console.
![\[App Runner service dashboard page showing the observability tab\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/service-dashboad-observability.png)
Use the Amazon CloudWatch console to view service maps and traces for requests that your application serves. Service maps show information like request latency and interactions with other applications and AWS services. The custom annotations that you add to your code allow you to easily search for traces. For more information, see [Using ServiceLens to monitor the health of your applications](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ServiceLens.html) in the *Amazon CloudWatch User Guide*.