# X-Ray

## Icon

![XRay](https://icon.icepanel.io/AWS/svg/Developer-Tools/X-Ray.svg)

## About

* `X-Ray` is an AWS offering which allows to in the following
  * Troubleshoot performance.
  * Understand dependencies in microservices architecture.
  * Review request behavior.
  * Find errors and exceptions.
  * SLA requirements can be accessed.
  * Throttling issues.
  * Identify users that are impacted
* X-Ray service map gives details about the api flow, service interaction in a nice graphical visual form, giving interesting insights.

## Compatibility

* Can be used along with many AWS services
  * Lambda
  * Elastic Beanstalk
  * ECS
  * ELB
  * API Gateway
  * EC2 instances or any application server *(even on premise)*

## Working

* `X-Ray` leverages tracing
* Tracing is a end to end way of following a `request`.
* Each component dealing with the request adds its own `trace`.
* Tracing is made of segments.
* Annotations can be added to trace to provide extra-information with capability to filter and search them.
* Ability to trace
  * Every request
  * Sample request *(as a % for example or a rate per minute)*
* X-Ray Security
  * IAM Authorization
  * KMS for encryption at rest

## Enable X-Ray

* To enable X-Ray, one must import the AWS `X-Ray` SDK.
* Install X-Ray daemon or enable X-Ray AWS integration in the AWS service.
  * It works as a UDP packet inspector.
* All application should have IAM rights to write data to `X-Ray`.
* Once all the above is done, **X-Ray daemon will send batch every 1 second to AWS X-Ray**.
* For lambda, X-Ray Active Tracing should be enabled in lambda function's configuration, so that above mentioned daemon can capture metrics. Ensure IAM execution role with proper policy is configured *(AWSX-RayWriteOnlyAccess)*.

## X-Ray Instrumentation

* `Instrumentation` means the measure of product's performance, diagnose errors, and to write trace information.
* To instrument your application code, use the X-Ray SDK.
* Mostly configuration changes are only required, however one can modify the application using interceptors, filters, handlers etc.

## X-Ray Concepts

* Segments
  * Each application/service will send them.
* Sub Segments
  * To provide more fine grain details in your segment.
* Trace
  * Segments collected together to form an end-to-end trace.
* Sampling
  * To decrease the amount of requests send to X-Ray to reduce cost.
  * It allows to control the amount of data that you record.
  * Sampling rules can be modified without changing code.
  * By default, the X-Ray SDK records the first request each second and five percent of additional requests based on default rule.
    * One request per second is the reservoir, which ensures that atleast one trace is recorded each second as long as the service is serving requests.
    * Five percent is the rate at which additional requests beyond the reservoir are sampled.
  * One can define their own sampling rules, along with **reservoir** and **rate**.
* Annotations
  * These are key-value pairs to index traces and use the filters.
* Metadata
  * Key-Value pairs, not indexed, not used for searching.

## X-Ray Daemon

* X-Ray daemon/agent has a config to send traces cross-account. - Make sure the IAM permissions are correct. The agent will assume the role.
* This allows to have central account for application tracing.
* Changing or creating a sampling rule does not need to restart X-Ray Daemon.
* X-Ray Daemon runs on port 2000 on a container or as process with UDP protocol as traffic.

## X-Ray APIs

* Segragate based on IAM Policy Access

### WriteOnly Access

* `PutTraceSegments`: Upload segment documents to AWS X-Ray
* `PutTelemetryRecords`: Used by the AWS X-Ray daemon to upload the telemetry.
* `GetSamplingRules`: Retrieving all sampling rules, used by AWS daemon so it doesnot have to restart to get updated sampled rules.
  * `GetSamplingTargets` & `GetSamplingStatisticsSummaries` are part of this rules.

### ReadOnly Access

* `GetServiceGraph`: Retrieves main graph
* `BatchGetTraces`: Retrieve a list of traces specified by ID. Each trace is a collection of segment documents that originates from a single request.
* `GetTraceSummaries`: Retrieve IDs and annotations for traces available for specified time frame using optional filter. To get full traces, pass the trace IDs to `BatchGetTraces`.
* `GetTraceGraph`: Retrieves a service graph for one or more specific trace IDs.
* X-Ray Daemon should have an IAM policy which authorizes the above API calls to retrieve the details.

## X-Ray Integration with other services

* **Beanstalk**: Already integrated, just need to be enable the option in `.ebextensions/xray-daemon.config` file or in console.
* **EC2 instance : X-Ray Container as Daemon**
  * Application container will run along with this daemon container per EC2 instance. i.e only one container per EC2 instance.
* **ECS cluster : X-Ray Container as** [**SideCar pattern**](https://aws.amazon.com/blogs/containers/using-sidecar-injection-on-amazon-eks-with-aws-app-mesh/)
  * X-Ray container will run alongside application container.
  * Both will connect to each other from networking context.
* **ECS Fargate cluster**
  * Similar to ECS cluster, the fargate task will have both the app container and `X-Ray SideCar` Container.