}
The tables that the application creates follow a consistent naming convention. You can use the format of scorekeep-* to indicate all tables following that convention.
To change your IAM policy
1. Open the Elastic Beanstalk instance profile in the IAM console: aws-elasticbeanstalk-ec2-role.
2. Remove the AmazonS3FullAccess and AmazonDynamoDBFullAccess policies from the role.
3. Choose Attach policies, and then Create policy.
4. Choose the JSON and paste in one of the policies created previously.
5. Choose Review policy.
6. For Name, assign a name.
7. Choose Create policy.
8. Assign the newly created policy to the aws-elasticbeanstalk-ec2-role.
9. Repeat for the second policy created previously.
Clean up
Terminate your Elastic Beanstalk environment to shut down the Amazon EC2 instances, DynamoDB tables, and other resources.
To terminate your Elastic Beanstalk environment
1. Open the Elastic Beanstalk console.2. Navigate to the management console for your environment.
3. Choose Actions.
4. Choose Terminate Environment.
5. Choose Terminate.
Trace data is automatically deleted from X-Ray after 30 days.
Next steps
Learn more about X-Ray in the next chapter, AWS X-Ray concepts (p. 16).
To instrument your own app, learn more about the X-Ray SDK for Java or one of the other X-Ray SDKs:
• X-Ray SDK for Java – AWS X-Ray SDK for Java (p. 228)
• X-Ray SDK for Node.js – AWS X-Ray SDK for Node.js (p. 265)
• X-Ray SDK for .NET – AWS X-Ray SDK for .NET (p. 305)
To run the X-Ray daemon locally or on AWS, see AWS X-Ray daemon (p. 165).
To contribute to the sample application on GitHub, see eb-java-scorekeep.
Segments
AWS X-Ray concepts
AWS X-Ray receives data from services as segments. X-Ray then groups segments that have a common request into traces. X-Ray processes the traces to generate a service graph that provides a visual representation of your application.
Concepts
• Segments (p. 16)
• Subsegments (p. 17)
• Service graph (p. 19)
• Traces (p. 20)
• Sampling (p. 21)
• Tracing header (p. 21)
• Filter expressions (p. 22)
• Groups (p. 22)
• Annotations and metadata (p. 23)
• Errors, faults, and exceptions (p. 23)
Segments
The compute resources running your application logic send data about their work as segments. A segment provides the resource's name, details about the request, and details about the work done. For example, when an HTTP request reaches your application, it can record the following data about:
• The host – hostname, alias or IP address
• The request – method, client address, path, user agent
• The response – status, content
• The work done – start and end times, subsegments
• Issues that occur – errors, faults and exceptions (p. 23), including automatic capture of exception stacks.
Subsegments
The X-Ray SDK gathers information from request and response headers, the code in your application, and metadata about the AWS resources on which it runs. You choose the data to collect by modifying your application configuration or code to instrument incoming requests, downstream requests, and AWS SDK clients.
Forwarded Requests
If a load balancer or other intermediary forwards a request to your application, X-Ray takes the client IP from the X-Forwarded-For header in the request instead of from the source IP in the IP packet. The client IP that is recorded for a forwarded request can be forged, so it should not be trusted.
You can use the X-Ray SDK to record additional information such as annotations and metadata. (p. 23) For details about the structure and information that is recorded in segments and subsegments, see AWS X-Ray segment documents (p. 121). Segment documents can be up to 64 kB in size.
Subsegments
A segment can break down the data about the work done into subsegments. Subsegments provide more granular timing information and details about downstream calls that your application made to fulfill the original request. A subsegment can contain additional details about a call to an AWS service, an external HTTP API, or an SQL database. You can even define arbitrary subsegments to instrument specific functions or lines of code in your application.
Subsegments
For services that don't send their own segments, like Amazon DynamoDB, X-Ray uses subsegments to generate inferred segments and downstream nodes on the service map. This lets you see all of your downstream dependencies, even if they don't support tracing, or are external.
Subsegments represent your application's view of a downstream call as a client. If the downstream service is also instrumented, the segment that it sends replaces the inferred segment generated from the upstream client's subsegment. The node on the service graph always uses information from the service's segment, if it's available, while the edge between the two nodes uses the upstream service's subsegment.
For example, when you call DynamoDB with an instrumented AWS SDK client, the X-Ray SDK records a subsegment for that call. DynamoDB doesn't send a segment, so the inferred segment in the trace, the DynamoDB node on the service graph, and the edge between your service and DynamoDB all contain information from the subsegment.
When you call another instrumented service with an instrumented application, the downstream service sends its own segment to record its view of the same call that the upstream service recorded in a subsegment. In the service graph, both services' nodes contain timing and error information from those services' segments, while the edge between them contains information from the upstream service's subsegment.
Service graph
Both viewpoints are useful, as the downstream service records precisely when it started and ended work on the request, and the upstream service records the round trip latency, including time that the request spent traveling between the two services.
Service graph
X-Ray uses the data that your application sends to generate a service graph. Each AWS resource that sends data to X-Ray appears as a service in the graph. Edges connect the services that work together to serve requests. Edges connect clients to your application, and your application to the downstream services and resources that it uses.
Service Names
A segment's name should match the domain name or logical name of the service that generates the segment. However, this is not enforced. Any application that has permission to PutTraceSegments can send segments with any name.
A service graph is a JSON document that contains information about the services and resources that make up your application. The X-Ray console uses the service graph to generate a visualization or service map.
Traces
For a distributed application, X-Ray combines nodes from all services that process requests with the same trace ID into a single service graph. The first service that the request hits adds a tracing header (p. 21) that is propagated between the front end and services that it calls.
For example, Scorekeep (p. 134) runs a web API that calls a microservice (an AWS Lambda function) to generate a random name by using a Node.js library. The X-Ray SDK for Java generates the trace ID and includes it in calls to Lambda. Lambda sends tracing data and passes the trace ID to the function.
The X-Ray SDK for Node.js also uses the trace ID to send data. As a result, nodes for the API, the Lambda service, and the Lambda function all appear as separate, but connected, nodes on the service map.
Service graph data is retained for 30 days.
Traces
A trace ID tracks the path of a request through your application. A trace collects all the segments generated by a single request. That request is typically an HTTP GET or POST request that travels through a load balancer, hits your application code, and generates downstream calls to other AWS services or external web APIs. The first supported service that the HTTP request interacts with adds a trace ID header to the request, and propagates it downstream to track the latency, disposition, and other request data.
Sampling
Service graph data is retained for 30 days.
Sampling
To ensure efficient tracing and provide a representative sample of the requests that your application serves, the X-Ray SDK applies a sampling algorithm to determine which requests get traced. By default, the X-Ray SDK records the first request each second, and five percent of any additional requests.
To avoid incurring service charges when you are getting started, the default sampling rate is
conservative. You can configure X-Ray to modify the default sampling rule and configure additional rules that apply sampling based on properties of the service or request.
For example, you might want to disable sampling and trace all requests for calls that modify state or handle user accounts or transactions. For high-volume read-only calls, like background polling, health checks, or connection maintenance, you can sample at a low rate and still get enough data to see any issues that arise.
For more information, see Configuring sampling rules in the X-Ray console (p. 76).
Tracing header
All requests are traced, up to a configurable minimum. After reaching that minimum, a percentage of requests are traced to avoid unnecessary cost. The sampling decision and trace ID are added to HTTP requests in tracing headers named X-Amzn-Trace-Id. The first X-Ray-integrated service that the request hits adds a tracing header, which is read by the X-Ray SDK and included in the response.
Example Tracing header with root trace ID and sampling decision
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Sampled=1
Filter expressions
Tracing Header Security
A tracing header can originate from the X-Ray SDK, an AWS service, or the client request. Your application can remove X-Amzn-Trace-Id from incoming requests to avoid issues caused by users adding trace IDs or sampling decisions to their requests.
The tracing header can also contain a parent segment ID if the request originated from an instrumented application. For example, if your application calls a downstream HTTP web API with an instrumented HTTP client, the X-Ray SDK adds the segment ID for the original request to the tracing header of the downstream request. An instrumented application that serves the downstream request can record the parent segment ID to connect the two requests.
Example Tracing header with root trace ID, parent segment ID and sampling decision
X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1
Filter expressions
Even with sampling, a complex application generates a lot of data. The AWS X-Ray console provides an easy-to-navigate view of the service graph. It shows health and performance information that helps you identify issues and opportunities for optimization in your application. For advanced tracing, you can drill down to traces for individual requests, or use filter expressions to find traces related to specific paths or users.
Groups
Extending filter expressions, X-Ray also supports the group feature. Using a filter expression, you can define criteria by which to accept traces into the group.
You can call the group by name or by Amazon Resource Name (ARN) to generate its own service graph, trace summaries, and Amazon CloudWatch metrics. Once a group is created, incoming traces are checked against the group’s filter expression as they are stored in the X-Ray service. Metrics for the number of traces matching each criteria are published to CloudWatch every minute.
Updating a group's filter expression doesn't change data that's already recorded. The update applies only to subsequent traces. This can result in a merged graph of the new and old expressions. To avoid this, delete the current group and create a fresh one.
Note
Groups are billed by the number of retrieved traces that match the filter expression. For more information, see AWS X-Ray pricing.For more information about groups, see Configuring groups in the X-Ray console (p. 90).
Annotations and metadata
Annotations and metadata
When you instrument your application, the X-Ray SDK records information about incoming and outgoing requests, the AWS resources used, and the application itself. You can add other information to the segment document as annotations and metadata. Annotations and metadata are aggregated at the trace level, and can be added to any segment or subsegment.
Annotations are simple key-value pairs that are indexed for use with filter expressions (p. 64). Use annotations to record data that you want to use to group traces in the console, or when calling the GetTraceSummaries API.
X-Ray indexes up to 50 annotations per trace.
Metadata are key-value pairs with values of any type, including objects and lists, but that are not indexed. Use metadata to record data you want to store in the trace but don't need to use for searching traces.
You can view annotations and metadata in the segment or subsegment details in the X-Ray console.
Errors, faults, and exceptions
X-Ray tracks errors that occur in your application code, and errors that are returned by downstream services. Errors are categorized as follows.
• Error – Client errors (400 series errors)
• Fault – Server faults (500 series errors)
• Throttle – Throttling errors (429 Too Many Requests)
Errors, faults, and exceptions
When an exception occurs while your application is serving an instrumented request, the X-Ray SDK records details about the exception, including the stack trace, if available. You can view exceptions under segment details (p. 60) in the X-Ray console.
Data protection
Security in AWS X-Ray
Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations.
Security is a shared responsibility between AWS and you. The shared responsibility model describes this as security of the cloud and security in the cloud:
• Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. The effectiveness of our security is regularly tested and verified by third-party auditors as part of the AWS compliance programs. To learn about the compliance programs that apply to X-Ray, see AWS Services in Scope by Compliance Program.
• Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your organization’s requirements, and applicable laws and regulations.
This documentation will help you understand how to apply the shared responsibility model when using X-Ray. The following topics show you how to configure X-Ray to meet your security and compliance objectives. You'll also learn how to use other AWS services that can help you to monitor and secure your X-Ray resources.
Topics
• Data protection in AWS X-Ray (p. 25)
• Identity and access management for AWS X-Ray (p. 27)
• Compliance validation for AWS X-Ray (p. 44)
• Resilience in AWS X-Ray (p. 44)
• Infrastructure security in AWS X-Ray (p. 45)
Data protection in AWS X-Ray
AWS X-Ray always encrypts traces and related data at rest. When you need to audit and disable encryption keys for compliance or internal requirements, you can configure X-Ray to use an AWS Key Management Service (AWS KMS) key to encrypt data.
X-Ray provides an AWS managed key named aws/xray. Use this key when you just want to audit key usage in AWS CloudTrail and don't need to manage the key itself. When you need to manage access to the key or configure key rotation, you can create a customer managed key.
When you change encryption settings, X-Ray spends some time generating and propagating data keys.
While the new key is being processed, X-Ray may encrypt data with a combination of the new and old settings. Existing data is not re-encrypted when you change encryption settings.
Note
AWS KMS charges when X-Ray uses a KMS key to encrypt or decrypt trace data.
• Default encryption – Free.
Data protection
• AWS managed key – Pay for key use.
• customer managed key – Pay for key storage and use.
See AWS Key Management Service Pricing for details.
Note
X-Ray insights notifications sends events to Amazon EventBridge, which does not currently support customer managed keys. For more information, see Data Protection in Amazon EventBridge.You must have user-level access to a customer managed key to configure X-Ray to use it, and to then view encrypted traces. See User permissions for encryption (p. 35) for more information.
X-Ray console
To configure X-Ray to use a KMS key for encryption using the X-Ray console
1. Open the X-Ray console.2. Choose Encryption.
3. Choose Use a KMS key.
4. Choose a key from the dropdown menu:
• aws/xray – Use the AWS managed key.
• key alias – Use a customer managed key in your account.
• Manually enter a key ARN – Use a customer managed key in a different account. Enter the full Amazon Resource Name (ARN) of the key in the field that appears.
5. Choose Apply.
CloudWatch console
To configure X-Ray to use a KMS key for encryption using the CloudWatch console
1. Sign in to the AWS Management Console and open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.
2. Choose Settings in the left navigation pane.
3. Choose View settings under Encryption within the X-Ray traces section.
4. Choose Edit in the Encryption configuration section.
5. Choose Use a KMS key.
6. Choose a key from the dropdown menu:
• aws/xray – Use the AWS managed key.
• key alias – Use a customer managed key in your account.
• Manually enter a key ARN – Use a customer managed key in a different account. Enter the full Amazon Resource Name (ARN) of the key in the field that appears.
7. Choose Update encryption.
Note
X-Ray does not support asymmetric KMS keys.If X-Ray is unable to access your encryption key, it stops storing data. This can happen if your user loses access to the KMS key, or if you disable a key that's currently in use. When this happens, X-Ray shows a notification in the navigation bar.
Identity and access management
To configure encryption settings with the X-Ray API, see Configuring sampling, groups, and encryption settings with the AWS X-Ray API (p. 113).
Identity and access management for AWS X-Ray
AWS Identity and Access Management (IAM) is an AWS service that helps an administrator securely control access to AWS resources. IAM administrators control who can be authenticated (signed in) and authorized (have permissions) to use X-Ray resources. IAM is an AWS service that you can use with no additional charge.
Topics
• Audience (p. 27)
• Authenticating with identities (p. 27)
• Managing access using policies (p. 29)
• How AWS X-Ray works with IAM (p. 31)
• AWS X-Ray identity-based policy examples (p. 35)
• Troubleshooting AWS X-Ray identity and access (p. 42)
Audience
How you use AWS Identity and Access Management (IAM) differs, depending on the work that you do in X-Ray.
Service user – If you use the X-Ray service to do your job, then your administrator provides you with the credentials and permissions that you need. As you use more X-Ray features to do your work, you might need additional permissions. Understanding how access is managed can help you request the right permissions from your administrator. If you cannot access a feature in Ray, see Troubleshooting AWS X-Ray identity and access (p. 42).
Service administrator – If you're in charge of X-Ray resources at your company, you probably have full access to X-Ray. It's your job to determine which X-Ray features and resources your employees should access. You must then submit requests to your IAM administrator to change the permissions of your service users. Review the information on this page to understand the basic concepts of IAM. To learn more about how your company can use IAM with X-Ray, see How AWS X-Ray works with IAM (p. 31).
IAM administrator – If you're an IAM administrator, you might want to learn details about how you can write policies to manage access to X-Ray. To view example X-Ray identity-based policies that you can use in IAM, see AWS X-Ray identity-based policy examples (p. 35).
Authenticating with identities
Authentication is how you sign in to AWS using your identity credentials. For more information about
Authentication is how you sign in to AWS using your identity credentials. For more information about