{"id":21042770,"url":"https://github.com/aws-observability/aws-otel-playground","last_synced_at":"2025-05-15T17:31:06.913Z","repository":{"id":46365069,"uuid":"224066118","full_name":"aws-observability/aws-otel-playground","owner":"aws-observability","description":"Sample Application for the AWS X-Ray SDK with support for OpenTelemetry","archived":false,"fork":false,"pushed_at":"2023-09-05T22:15:05.000Z","size":608,"stargazers_count":35,"open_issues_count":1,"forks_count":15,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-04-03T12:11:39.482Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-observability.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-26T00:16:13.000Z","updated_at":"2025-01-06T13:10:46.000Z","dependencies_parsed_at":"2023-01-20T07:28:12.833Z","dependency_job_id":null,"html_url":"https://github.com/aws-observability/aws-otel-playground","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-playground","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-playground/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-playground/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-observability%2Faws-otel-playground/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-observability","download_url":"https://codeload.github.com/aws-observability/aws-otel-playground/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254388057,"owners_count":22062977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T14:08:59.021Z","updated_at":"2025-05-15T17:31:06.555Z","avatar_url":"https://github.com/aws-observability.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# X-Ray Instrumentation Playground\n\nThis repository contains a toy application which exhibits a simple yet somewhat representative trace,\nincluding AWS SDK calls, a frontend and backend, and HTTP and gRPC.\n\nThe same application is instrumented in several ways, allowing us to compare the experience when viewing\ntraces for the different types of instrumentation.\n\nCurrent instrumentation includes\n- OpenTelemetry Auto Instrumentation + OpenTelemetry Collector\n- X-Ray SDK Instrumentation + X-Ray Daemon\n  - Does not instrument many libraries like gRPC and Lettuce\n\n## Setting up AWS resources\n\nThe playground access various endpoints hosted on AWS. Feel free to skip this section to just see traces with local endpoints.\n\nTo set up AWS resources you will need Terraform, available [here](https://www.terraform.io/downloads.html).\n\nFirst, make sure your have configured AWS credentials using the AWS CLI as described [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html).\n\nYou must also have [Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) installed to build the project.\n\nFrom the root of the repository, to prepare the lambda deployment, run\n\n```\n$ ./gradlew :lambda-api:build\n```\n\nThen, navigate to the `scripts/terraform` directory and run\n\n```\n$ terraform init\n$ terraform apply\n```\n\nThis will take some time as it provisions resources. Note that this also generates `terraform.tfstate` files in the\nsame directory. DO NOT LOSE THESE - without these files, Terraform will not be able to cleanup after you are done with the\nresources.\n\nAfter it completes, three output values will be printed. Open `docker-compose.yml` and find the four values under `#AWS Provisioned resources`\nChange the values so\n\n- `API_GATEWAY_ENDPOINT` is set to the output value `lambda_api_gateway_url`\n- `ECS_ENDPOINT` is set to the output value `ecs_url`\n- `EKS_ENDPOINT` is set to the output value `eks_fargate_url`\n- `OTEL_ENDPOINT_PEER_SERVICE_MAPPING` - replace the keys for hello-lambda-api, ecs-backend, eks-backend to the domains for these three values\n\n## Running\n\nMake sure Docker is installed and run\n\n`$ docker-compose up`\n\nAccess `http://localhost:9080/`.\n\nThen visit the X-Ray console, for example [here](https://ap-northeast-1.console.aws.amazon.com/xray/home?region=ap-northeast-1#/traces)\nand you should see multiple traces corresponding to the request you made.\n\nThe app uses normal [AWS credentials](https://docs.aws.amazon.com/sdk-for-java/v2/developer-guide/setup-credentials.html).\nIf you have trouble running after using the CLI to run `aws configure`, try setting the environment variables as described\non that page, in particular `AWS_REGION`.\n\nNote that the `dynamodb-table` is only to create the table once, so it is normal for it to exist after creating the table.\n\nIf you see excessive deadline exceeded errors or the page doesn't respond properly, your Docker configuration may not have enough RAM.\nWe recommend setting Docker to 4GB of RAM for a smooth experience.\n\nIf you make any code edits you would like to try out, first rebuild the Docker images locally.\n\n`./gradlew jibDockerBuild`\n\nand then rerun docker-compose.\n\n## Cleaning up\n\nIf you provisioned AWS resources above, run `terraform destroy` to clean them up.\n\n## How it works\n\nThe playground is composed of two observability components in addition to the business logic actually being monitored.\n\n- [OpenTelemetry Java Agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation)\n- [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib)\n\nThe recommended way to get started for your app is to run the Docker image for the collector from [here](https://hub.docker.com/r/otel/opentelemetry-collector-contrib-dev).\nThe collector listens on port 55680 for telemetry.\n\nYou will need to provide a path to a configuration file with the `--config` parameter when running. This basic configuration\nwill work for X-Ray.\n\n```yaml\nreceivers:\n  otlp:\n    protocols:\n      grpc:\nexporters:\n  logging:\n    loglevel: info\n  awsxray:\n    local_mode: true\nprocessors:\n  memory_limiter:\n    limit_mib: 100\n    check_interval: 5s\nservice:\n  pipelines:\n    traces:\n      processors:\n      - memory_limiter\n      receivers:\n      - otlp\n      exporters:\n      - logging\n      - awsxray\n      # Feel free to add more exporters if you use e.g., Zipkin, Jaeger\n```\n\nIf you have AWS credentials configured and both apps running on localhost, you will see traces in X-Ray if you issue any\nrequests. If the collector cannot be accessed via localhost (e.g., in docker-compose), you may need to set the endpoint when\nstarting your Java application using the `OTEL_OTLP_ENDPOINT` environment variable.\n\n# License\n\nThis project is licensed under the MIT No Attribution License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-observability%2Faws-otel-playground","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-observability%2Faws-otel-playground","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-observability%2Faws-otel-playground/lists"}