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). # Observability for your App Runner service AWS App Runner integrates with several AWS services to provide you with an extensive observability suite of tools for your App Runner service. Topics in this chapter describe these capabilities. **Topics** + [Tracking App Runner service activity](monitor-activity.md) + [Viewing App Runner logs streamed to CloudWatch Logs](monitor-cwl.md) + [Viewing App Runner service metrics reported to CloudWatch](monitor-cw.md) + [Handling App Runner events in EventBridge](monitor-ev.md) + [Logging App Runner API calls with AWS CloudTrail](monitor-ct.md) + [Tracing for your App Runner application with X-Ray](monitor-xray.md) # Tracking App Runner service activity AWS App Runner uses a list of operations to keep track of activity in your App Runner service. An operation represents an asynchronous call to an API action, such as creating a service, updating a configuration, and deploying a service. The following sections show you how to track activity in the App Runner console and using the API. ## Track App Runner service activity Track your App Runner service activity using one of the following methods: ------ #### [ App Runner console ] The App Runner console displays your App Runner service activity and provides more ways to explore operations. **To view activity of your service** 1. Open the [App Runner console](https://console.aws.amazon.com/apprunner), and in the **Regions** list, select your AWS Region. 1. In the navigation pane, choose **Services**, and then choose your App Runner service. The console displays the service dashboard with a **Service overview**. ![\[App Runner service dashboard page showing Activity list\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/console-dashboard.png) 1. On the service dashboard page, choose the **Activity** tab, if it isn't already chosen. The console displays a list of operations. 1. To find specific operations, scope down the list by entering a search term. You can search for any value that appears in the table. 1. Choose any listed operation to see or download the related log. ------ #### [ App Runner API or AWS CLI ] The [ListOperations](https://docs.aws.amazon.com/apprunner/latest/api/API_ListOperations.html) action, given the Amazon Resource Name (ARN) of an App Runner service, returns a list of operations that occurred on this service. Each list item contains an operation ID and some tracking details. ------ # Viewing App Runner logs streamed to CloudWatch Logs You can use Amazon CloudWatch Logs to monitor, store, and access log files that your resources in various AWS services generate. For more information, see [Amazon CloudWatch Logs User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/). AWS App Runner collects the output of your application deployments and of your active service and streams it to CloudWatch Logs. The following sections list App Runner log streams and show you how to view them in the App Runner console. ## App Runner log groups and streams CloudWatch Logs keeps log data in log streams that it further organizes in log groups. A *log stream* is a sequence of log events from a specific source. A *log group* is a group of log streams that share the same retention, monitoring, and access control settings. App Runner defines two CloudWatch Logs log groups, each with multiple log streams, for each App Runner service in your AWS account. ### Service logs The service log group contains logging output generated by App Runner as it manages your App Runner service and acts on it. | **Log group name** | **Example** | | --- | --- | | `/aws/apprunner/service-name/service-id/service` | `/aws/apprunner/python-test/ac7ec8b51ff34746bcb6654e0bcb23da/service` | Within the service log group, App Runner creates an events log stream to capture activity in the lifecycle of your App Runner service. For example, this might be launching your application or pausing it. In addition, App Runner creates a log stream for each long-running asynchronous operation that's related to your service. The log stream name reflects the operation type and specific operation ID. A *deployment* is a type of operation. Deployment logs contain the logging output of the build and deployment steps that App Runner performs when you create a service or deploy a new version of your application. Deployment log stream names start with `deployment/`, and end with the ID of the operation that performs the deployment. This operation is either a [CreateService](https://docs.aws.amazon.com/apprunner/latest/api/API_CreateService.html) call for the initial application deployment or a [StartDeployment](https://docs.aws.amazon.com/apprunner/latest/api/API_StartDeployment.html) call for each further deployment. Within a deployment log, each log message starts with a prefix: + `[AppRunner]` – Output that App Runner generates during the deployment. + `[Build]` – Output of your own build scripts. | **Log stream name** | **Example** | | --- | --- | | `events` | *N/A (fixed name)* | | `operation-type/operation-id` | `deployment/c2c8eeedea164f459cf78f12a8953390` | ### Application logs The application log group contains the output of your running application code. | **Log group name** | **Example** | | --- | --- | | `/aws/apprunner/service-name/service-id/application` | `/aws/apprunner/python-test/ac7ec8b51ff34746bcb6654e0bcb23da/application` | Within the application log group, App Runner creates a log stream for each instance (scaling unit) that's running your application. | **Log stream name** | **Example** | | --- | --- | | `instance/instance-id` | `instance/1a80bc9134a84699b7b3432ebeebb591` | ## Viewing App Runner logs in the console The App Runner console displays a summary of all logs for your service and allows you to view, explore, and download them. **To view logs for your service** 1. Open the [App Runner console](https://console.aws.amazon.com/apprunner), and in the **Regions** list, select your AWS Region. 1. In the navigation pane, choose **Services**, and then choose your App Runner service. The console displays the service dashboard with a **Service overview**. ![\[App Runner service dashboard page showing Activity list\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/console-dashboard.png) 1. On the service dashboard page, choose the **Logs** tab. The console displays a few types of logs in several sections: + **Event log** – Activity in the lifecycle of your App Runner service. The console displays the latest events. + **Deployment logs** – Source repository deployments to your App Runner service. The console displays a separate log stream for each deployment. + **Application logs** – The output of the web application that's deployed to your App Runner service. The console combines the output from all running instances into a single log stream. ![\[The Logs tab on the App Runner service dashboard page\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/service-dashboad-logs.png) 1. To find specific deployments, scope down the deployment log list by entering a search term. You can search for any value that appears in the table. 1. To view a log's content, choose **View full log** (event log) or the log stream name (deployment and application logs). 1. Choose **Download** to download a log. For a deployment log stream, select a log stream first. 1. Choose **View in CloudWatch** to open the CloudWatch console and use its full capabilities to explore your App Runner service logs. For a deployment log stream, select a log stream first. **Note** The CloudWatch console is particularly useful if you want to view application logs of specific instances instead of the combined application log. # Viewing App Runner service metrics reported to CloudWatch Amazon CloudWatch monitors your Amazon Web Services (AWS) resources and the applications you run on AWS in real time. You can use CloudWatch to collect and track metrics, which are variables you can measure for your resources and applications. You can also use it to create alarms that watch metrics. When a certain threshold is reached, CloudWatch sends notifications, or automatically makes changes to the monitored resources. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). AWS App Runner collects a variety of metrics that provide you with greater visibility into the usage, performance, and availability of your App Runner services. Some metrics track individual instances that run your web service, whereas others are at the overall service level. The following sections list App Runner metrics and show you how to view them in the App Runner console. ## App Runner metrics App Runner collects the following metrics relating to your service and publishes them to CloudWatch in the `AWS/AppRunner` namespace. **Note** Prior to August 23, 2023, the **CPU utilization** and **Memory utilization** metrics were based on vCPU units and megabytes of memory utilized, instead of *percent utilization*, as calculated today. If your application ran on App Runner before this date, and you choose to go back to view metrics for this date on either the App Runner or the CloudWatch console, you'll see a display of the metrics in both units and will also see some irregularities as a result. **Important** You'll need to update any CloudWatch alarms that are based on the *CPU utilization* and *Memory utilization* metric values prior to August 23, 2023. Update the alarms to trigger based on percentage utilization rather than vCPU or megabytes. For more information, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). **Instance level metrics** are collected for each instance (scaling unit) individually. | **What's measured?** | **Metric** | **Description** | | --- | --- | --- | | CPU utilization | `CPUUtilization` | The percentage of average CPU usage during one-minute periods out of the total CPU usage reserved by the service configuration. | | Memory utilization | `MemoryUtilization` | The percentage of average memory usage during one-minute periods out of the total memory reserved by the service configuration. | **Service level metrics** are collected for the entire service. | **What's measured?** | **Metric** | **Description** | | --- | --- | --- | | CPU utilization | `CPUUtilization` | The percentage of aggregated CPU usage across all instances during one minute periods out of the total CPU usage reserved by the service configuration. | | Memory utilization | `MemoryUtilization` | The percentage of aggregated memory usage across all instances during one minute periods out of the total memory reserved by the service configuration. | | Concurrency | `Concurrency` | The approximate number of concurrent requests being handled by the service. | | HTTP request count | `Requests` | The number of HTTP requests that the service received. | | HTTP status counts | `2xxStatusResponses` `4xxStatusResponses` `5xxStatusResponses` | The number of HTTP requests that returned each response status, grouped by category (2XX, 4XX, 5XX). | | HTTP request latency | `RequestLatency` | The time, in milliseconds, that it took your web service to process HTTP requests. | | Instance counts | `ActiveInstances` | The number of instances that are processing HTTP requests for your service. If the `ActiveInstances` metric displays zero, it means that there are no requests for the service. It does not indicate that the number of instances for your service is zero. | ## Viewing App Runner metrics in the console The App Runner console graphically displays the metrics that App Runner collects for your service and provides more ways to explore them. **Note** At this time, the console displays only service metrics. To view instance metrics, use the CloudWatch console. **To view logs for your service** 1. Open the [App Runner console](https://console.aws.amazon.com/apprunner), and in the **Regions** list, select your AWS Region. 1. In the navigation pane, choose **Services**, and then choose your App Runner service. The console displays the service dashboard with a **Service overview**. ![\[App Runner service dashboard page showing Activity list\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/console-dashboard.png) 1. On the service dashboard page, choose the **Metrics** tab. The console displays a set of metrics graphs. ![\[The Metrics tab on the App Runner service dashboard page\]](http://docs.aws.amazon.com/apprunner/latest/dg/images/service-dashboad-metrics.png) 1. Choose a duration (for example, **12h**) to scope metrics graphs to the recent period of that duration. 1. Choose **Add to dashboard** at the top of one of the graph sections, or use the menu on any graph, to add the relevant metrics to a dashboard in the CloudWatch console for further investigation. # Handling App Runner events in EventBridge Using Amazon EventBridge, you can set up event-driven rules that monitor a stream of real-time data from your AWS App Runner service for certain patterns. When a pattern for a rule is matched, EventBridge initiates an action in a target such as AWS Lambda, Amazon ECS, AWS Batch, and Amazon SNS. For example, you can set a rule for sending out email notifications by signaling an Amazon SNS topic whenever a deployment to your service fails. Or, you can set a Lambda function to notify a Slack channel whenever a service update fails. For more information about EventBridge, see [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/). App Runner sends the following event types to EventBridge + *Service status change* – A change in the status of an App Runner service. For example, a service status changed to `DELETE_FAILED`. + *Service operation status change* – A change in the status of a long, asynchronous operation on an App Runner service. For example, a service started to create, a service update successfully completed, or a service deployment completed with errors. ## Creating an EventBridge rule to act on App Runner events An EventBridge *event* is an object that defines some standard EventBridge fields, such as the source AWS service and the detail (event) type, and an event-specific set of fields with the event details. To create an EventBridge rule, you use the EventBridge console to define an *event pattern* (which events should bet tracked) and specify a *target action* (what should be done on a match). An event pattern is similar to the events that it matches. You specify a subset of fields to match, and for each field, you specify a list of possible values. This topic provides examples of App Runner events and event patterns. For more information about creating EventBridge rules, see [Creating a rule for an AWS service](https://docs.aws.amazon.com/eventbridge/latest/userguide/create-eventbridge-rule.html) in the *Amazon EventBridge User Guide*. **Note** Some services support *pre-defined patterns* in EventBridge. This simplifies how an event pattern is created. You select field values on a form, and EventBridge generates the pattern for you. At this time, App Runner doesn't support pre-defined patterns. You have to enter the pattern as a JSON object. You can use the examples in this topic as a starting point. ## App Runner event examples These are some examples to events that App Runner sends to EventBridge. + A service status change event. Specifically, a service that changed from the `OPERATION_IN_PROGRESS` to the `RUNNING` status. ``` { "version": "0", "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", "detail-type": "AppRunner Service Status Change", "source": "aws.apprunner", "account": "111122223333", "time": "2021-04-29T11:54:23Z", "region": "us-east-2", "resources": [ "arn:aws:apprunner:us-east-2:123456789012:service/my-app/8fe1e10304f84fd2b0df550fe98a71fa" ], "detail": { "previousServiceStatus": "OPERATION_IN_PROGRESS", "currentServiceStatus": "RUNNING", "serviceName": "my-app", "serviceId": "8fe1e10304f84fd2b0df550fe98a71fa", "message": "Service status is set to RUNNING.", "severity": "INFO" } } ``` + An operation status change event. Specifically, an `UpdateService` operation that completed successfully. ``` { "version": "0", "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718", "detail-type": "AppRunner Service Operation Status Change", "source": "aws.apprunner", "account": "111122223333", "time": "2021-04-29T18:43:48Z", "region": "us-east-2", "resources": [ "arn:aws:apprunner:us-east-2:123456789012:service/my-app/8fe1e10304f84fd2b0df550fe98a71fa" ], "detail": { "operationStatus": "UpdateServiceCompletedSuccessfully", "serviceName": "my-app", "serviceId": "8fe1e10304f84fd2b0df550fe98a71fa", "message": "Service update completed successfully. New application and configuration is deployed.", "severity": "INFO" } } ``` ## App Runner event pattern examples The following examples demonstrate event patterns that you can use in EventBridge rules to match one or more App Runner events. An event pattern is similar to an event. Include only the fields that you want to match, and provide a list instead of a scalar to each one. + Match all service status change events for services of a specific account, where the service is no longer in `RUNNING` status. ``` { "detail-type": [ "AppRunner Service Status Change" ], "source": [ "aws.apprunner" ], "account": [ "111122223333" ], "detail": { "previousServiceStatus": [ "RUNNING" ] } } ``` + Match all operation status change events for services of a specific account, where the operation failed. ``` { "detail-type": [ "AppRunner Service Operation Status Change" ], "source": [ "aws.apprunner" ], "account": [ "111122223333" ], "detail": { "operationStatus": [ "CreateServiceFailed", "DeleteServiceFailed", "UpdateServiceFailed", "DeploymentFailed", "PauseServiceFailed", "ResumeServiceFailed" ] } } ``` ## App Runner event reference ### Service status change A service status change event has `detail-type` set to `AppRunner Service Status Change`. It has the following detail fields and values: ``` "serviceId": "your service ID", "serviceName": "your service name", "message": "Service status is set to CurrentStatus.", "previousServiceStatus": "any valid service status", "currentServiceStatus": "any valid service status", "severity": "varies" ``` ### Operation status change An operation status change event has `detail-type` set to `AppRunner Service Operation Status Change`. It has the following detail fields and values: ``` "operationStatus": "see following table", "serviceName": "your service name", "serviceId": "your service ID", "message": "see following table", "severity": "varies" ``` The following table lists all possible status codes and related messages. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/apprunner/latest/dg/monitor-ev.html) # Logging App Runner API calls with AWS CloudTrail App Runner is integrated with AWS CloudTrail, a service that provides a record of actions taken by a user, role, or an AWS service in App Runner. CloudTrail captures all API calls for App Runner as events. The calls captured include calls from the App Runner console and code calls to the App Runner API operations. If you create a trail, you can enable continuous delivery of CloudTrail events to an Amazon S3 bucket, including events for App Runner. If you don't configure a trail, you can still view the most recent events in the CloudTrail console in **Event history**. Using the information collected by CloudTrail, you can determine the request that was made to App Runner, the IP address from where the request was made, who made the request, when it was made, and additional details. To learn more about CloudTrail, see the [AWS CloudTrail User Guide](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/). ## App Runner information in CloudTrail CloudTrail is enabled on your AWS account when you create the account. When activity occurs in App Runner, that activity is recorded in a CloudTrail event along with other AWS service events in **Event history**. You can view, search, and download recent events in your AWS account. For more information, see [Viewing Events with CloudTrail Event History](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html). For an ongoing record of events in your AWS account, including events for App Runner, create a trail. A *trail* enables CloudTrail to deliver log files to an Amazon S3 bucket. By default, when you create a trail in the console, the trail applies to all AWS Regions. The trail logs events from all Regions in the AWS partition and delivers the log files to the Amazon S3 bucket that you specify. Additionally, you can configure other AWS services to further analyze and act upon the event data collected in CloudTrail logs. For more information, see the following: + [Overview for Creating a Trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html) + [CloudTrail Supported Services and Integrations](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations) + [Configuring Amazon SNS Notifications for CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html) + [Receiving CloudTrail Log Files from Multiple Regions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) and [Receiving CloudTrail Log Files from Multiple Accounts](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) All App Runner actions are logged by CloudTrail and are documented in the AWS App Runner API Reference. For example, calls to the `CreateService`, `DeleteConnection`, and `StartDeployment` actions generate entries in the CloudTrail log files. Every event or log entry contains information about who generated the request. The identity information helps you determine the following: + Whether the request was made with root or IAM user credentials. + Whether the request was made with temporary security credentials for a role or federated user. + Whether the request was made by another AWS service. For more information, see the [CloudTrail userIdentity Element](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). ## Understanding App Runner log file entries A trail is a configuration that enables delivery of events as log files to an Amazon S3 bucket that you specify. CloudTrail log files contain one or more log entries. An event represents a single request from any source and includes information about the requested action, the date and time of the action, and request parameters. CloudTrail log files aren't an ordered stack trace of the public API calls, so they don't appear in any specific order. The following example shows a CloudTrail log entry that demonstrates the `CreateService` action. **Note** For security reasons, some property values are redacted in the logs and replaced with the text `HIDDEN_DUE_TO_SECURITY_REASONS`. This prevents unintended exposure of secret information. However, you can still see that these properties were passed in the request or returned in the response. ### Example CloudTrail log entry for the `CreateService` App Runner action ``` { "eventVersion": "1.08", "userIdentity": { "type": "IAMUser", "principalId": "AIDACKCEVSQ6C2EXAMPLE", "arn": "arn:aws:iam::123456789012:user/aws-user", "accountId": "123456789012", "accessKeyId": "AKIAIOSFODNN7EXAMPLE", "userName": "aws-user" }, "eventTime": "2020-10-02T23:25:33Z", "eventSource": "apprunner.amazonaws.com", "eventName": "CreateService", "awsRegion": "us-east-2", "sourceIPAddress": "192.0.2.0", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3865.75 Safari/537.36", "requestParameters": { "serviceName": "python-test", "sourceConfiguration": { "codeRepository": { "repositoryUrl": "https://github.com/github-user/python-hello", "sourceCodeVersion": { "type": "BRANCH", "value": "main" }, "codeConfiguration": { "configurationSource": "API", "codeConfigurationValues": { "runtime": "python3", "buildCommand": "HIDDEN_DUE_TO_SECURITY_REASONS", "startCommand": "HIDDEN_DUE_TO_SECURITY_REASONS", "port": "8080", "runtimeEnvironmentVariables": "HIDDEN_DUE_TO_SECURITY_REASONS" } } }, "autoDeploymentsEnabled": true, "authenticationConfiguration": { "connectionArn": "arn:aws:apprunner:us-east-2:123456789012:connection/your-connection/e7656250f67242d7819feade6800f59e" } }, "healthCheckConfiguration": { "protocol": "HTTP" }, "instanceConfiguration": { "cpu": "256", "memory": "1024" } }, "responseElements": { "service": { "serviceName": "python-test", "serviceId": "dfa2b7cc7bcb4b6fa6c1f0f4efff988a", "serviceArn": "arn:aws:apprunner:us-east-2:123456789012:service/python-test/dfa2b7cc7bcb4b6fa6c1f0f4efff988a", "serviceUrl": "generated domain", "createdAt": "2020-10-02T23:25:32.650Z", "updatedAt": "2020-10-02T23:25:32.650Z", "status": "OPERATION_IN_PROGRESS", "sourceConfiguration": { "codeRepository": { "repositoryUrl": "https://github.com/github-user/python-hello", "sourceCodeVersion": { "type": "Branch", "value": "main" }, "sourceDirectory": "/", "codeConfiguration": { "codeConfigurationValues": { "configurationSource": "API", "runtime": "python3", "buildCommand": "HIDDEN_DUE_TO_SECURITY_REASONS", "startCommand": "HIDDEN_DUE_TO_SECURITY_REASONS", "port": "8080", "runtimeEnvironmentVariables": "HIDDEN_DUE_TO_SECURITY_REASONS" } } }, "autoDeploymentsEnabled": true, "authenticationConfiguration": { "connectionArn": "arn:aws:apprunner:us-east-2:123456789012:connection/your-connection/e7656250f67242d7819feade6800f59e" } }, "healthCheckConfiguration": { "protocol": "HTTP", "path": "/", "interval": 5, "timeout": 2, "healthyThreshold": 3, "unhealthyThreshold": 5 }, "instanceConfiguration": { "cpu": "256", "memory": "1024" }, "autoScalingConfigurationSummary": { "autoScalingConfigurationArn": "arn:aws:apprunner:us-east-2:123456789012:autoscalingconfiguration/DefaultConfiguration/1/00000000000000000000000000000001", "autoScalingConfigurationName": "DefaultConfiguration", "autoScalingConfigurationRevision": 1 } } }, "requestID": "1a60af60-ecf5-4280-aa8f-64538319ba0a", "eventID": "e1a3f623-4d24-4390-a70b-bf08a0e24669", "readOnly": false, "eventType": "AwsApiCall", "recipientAccountId": "123456789012" } ``` # 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*.