{"id":15707695,"url":"https://github.com/thenets/dotnet-xray-example","last_synced_at":"2025-06-20T03:07:21.100Z","repository":{"id":87614349,"uuid":"305873626","full_name":"thenets/dotnet-xray-example","owner":"thenets","description":null,"archived":false,"fork":false,"pushed_at":"2020-10-21T03:16:50.000Z","size":668,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-20T01:36:59.531Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thenets.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-21T01:17:22.000Z","updated_at":"2020-10-21T03:16:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"e5c8d6ec-fd43-45ce-b6b8-1e52e82b609a","html_url":"https://github.com/thenets/dotnet-xray-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thenets/dotnet-xray-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenets%2Fdotnet-xray-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenets%2Fdotnet-xray-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenets%2Fdotnet-xray-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenets%2Fdotnet-xray-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thenets","download_url":"https://codeload.github.com/thenets/dotnet-xray-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thenets%2Fdotnet-xray-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260868909,"owners_count":23074961,"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-10-03T20:41:07.966Z","updated_at":"2025-06-20T03:07:16.057Z","avatar_url":"https://github.com/thenets.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dotnet-xray-example\n\nExample of an .NET Core Web Application using the AWS X-Ray.\n\nThis repo have the code already done, but the instructions below will guide you throw all the steps required to set up a .NET application and instruments it to send the APM data to the AWS X-Ray.\n\n**ATTENTION**: It'll not work if you are running locally! You must be inside a EC2 instance or Fargate. Check the official documentation if you want to run locally: https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon-local.html\n\n## Requirements\n\nBefore we start, you'll need the following packages:\n- .NET Core: https://docs.microsoft.com/en-us/dotnet/core/install/linux-centos\n- Docker: `sudo amazon-linux-extras install docker`\n\nI'm using `Amazon Linux 2` to run this test.\n\n## Preparing the environment\n\n### IAM permissions\n\nYour application will need custom permissions to send data to the X-Ray service.\n\n- For ECS: add the policy below to the `Task Execution Role`.\n- For EC2: add the policy below to the `Instance Role`.\n\nAWS has a policy already created called `AWSXRayDaemonWriteAccess`. You can just attach it. Or you can create a new one using the JSON below:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"xray:PutTraceSegments\",\n                \"xray:PutTelemetryRecords\",\n                \"xray:GetSamplingRules\",\n                \"xray:GetSamplingTargets\",\n                \"xray:GetSamplingStatisticSummaries\"\n            ],\n            \"Resource\": [\n                \"*\"\n            ]\n        }\n    ]\n}\n```\n\n## Application\n\n### Creating a sample application\n\nCreate a new web application using the `dotnet` CLI:\n\n```bash\n# Go to the new project dir\n# (must be an empty dir)\nmkdir -p ~/projects/dotnet-xray-example\ncd ~/projects/dotnet-xray-example\n\n# Create the project from scaffold\ndotnet new webapp\n```\n\n### Instrumenting the application\n\nInstall the libraries:\n\nhttps://www.nuget.org/packages/AWSXRayRecorder.Handlers.AspNetCore/\n\n```bash\ndotnet add package AWSXRayRecorder.Handlers.AspNetCore --version 2.7.1\n```\n\nAdd the X-Ray to the startup application. Pay attention to the three parts:\n- Libraries at the beggining of the file\n- Configuration reader at `public Startup(IConfiguration configuration)`\n- The middleware responsible to send the data to the X-Ray Daemon at `public void Configure(IApplicationBuilder app, IWebHostEnvironment env)`\n\n**File**: [./Startup.cs](./Startup.cs)\n```cs\n\n[...]\n\nusing Amazon.XRay.Recorder.Core;\nusing Amazon.XRay.Recorder.Handlers.AspNetCore;\nnamespace dotnet_xray_example\n{\n    public class Startup\n    {\n        public Startup(IConfiguration configuration)\n        {\n            Configuration = configuration;\n\n            // AWS X-Ray\n            // pass IConfiguration object that reads appsettings.json file\n            AWSXRayRecorder.InitializeInstance(configuration);\n        }\n\n\n        [...]\n\n        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.\n        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)\n        { \n            \n            if (env.IsDevelopment())\n            {\n                app.UseDeveloperExceptionPage();\n            }\n            else\n            {\n                app.UseExceptionHandler(\"/Error\");\n                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.\n                app.UseHsts();\n                \n                // AWS X-Ray (production mode only)\n                // Application name\n                app.UseXRay(\"dotnet-test\");\n            }\n            \n        [...]\n```\n\n### Setting up the X-Ray daemon\n\nDoes exist two parts to setup the daemon:\n\n1. First, install the daemon. I'll consider that you'll use Linux container to run the application:\n\n**File**: [./Dockerfile](./Dockerfile)\n```dockerfile\n[...]\nCOPY ./entrypoint.sh ./out/\n[...]\nRUN set -x \\\n    # Install AWS X-Ray Daemon\n    \u0026\u0026 apt-get update \\\n    \u0026\u0026 apt-get install -y --no-install-recommends apt-transport-https curl ca-certificates wget \\\n    \u0026\u0026 apt-get clean \\\n    \u0026\u0026 apt-get autoremove \\\n    \u0026\u0026 rm -rf /var/lib/apt/lists/* \\\n    \u0026\u0026 wget -q https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.deb \\\n    \u0026\u0026 dpkg -i aws-xray-daemon-3.x.deb \\\n    # Set permission\n    \u0026\u0026 chmod +x entrypoint.sh\n\nENTRYPOINT [\"./entrypoint.sh\"]\n```\n\n2. Second, create the `entrypoint.sh` script to start the X-Ray Daemon, then start the application:\n\n**File**: [./entrypoint.sh](./entrypoint.sh)\n```bash\n#!/bin/bash\n\n# Start AWS X-Ray in background\n/usr/bin/xray --bind=0.0.0.0:2000 --bind-tcp=0.0.0.0:2000 \u0026\n\n# Start app\ndotnet dotnet-xray-example.dll\n```\n\n# Test\n\n```bash\nmake build\nmake run\n\n# Server will start at http://localhost:5000\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenets%2Fdotnet-xray-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthenets%2Fdotnet-xray-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthenets%2Fdotnet-xray-example/lists"}