{"id":21153032,"url":"https://github.com/opentracing-contrib/java-xray-tracer","last_synced_at":"2025-07-09T10:33:31.264Z","repository":{"id":47046611,"uuid":"171882780","full_name":"opentracing-contrib/java-xray-tracer","owner":"opentracing-contrib","description":"Java OpenTracing implementation backed by AWS X-Ray","archived":false,"fork":false,"pushed_at":"2023-12-05T22:20:25.000Z","size":129,"stargazers_count":23,"open_issues_count":6,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-04T22:11:31.428Z","etag":null,"topics":["aws","aws-xray","java","opentracing"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opentracing-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2019-02-21T14:05:02.000Z","updated_at":"2023-04-28T08:09:23.000Z","dependencies_parsed_at":"2024-11-20T11:23:24.412Z","dependency_job_id":"a5578a49-c002-462e-a2a6-e165544135c3","html_url":"https://github.com/opentracing-contrib/java-xray-tracer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/opentracing-contrib/java-xray-tracer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-xray-tracer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-xray-tracer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-xray-tracer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-xray-tracer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opentracing-contrib","download_url":"https://codeload.github.com/opentracing-contrib/java-xray-tracer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opentracing-contrib%2Fjava-xray-tracer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264440468,"owners_count":23608720,"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":["aws","aws-xray","java","opentracing"],"created_at":"2024-11-20T10:48:13.981Z","updated_at":"2025-07-09T10:33:30.835Z","avatar_url":"https://github.com/opentracing-contrib.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/opentracing-contrib/java-xray-tracer.svg?branch=master)](https://travis-ci.org/opentracing-contrib/java-xray-tracer) [![Coverage Status](https://coveralls.io/repos/github/opentracing-contrib/java-xray-tracer/badge.svg?branch=master)](https://coveralls.io/github/opentracing-contrib/java-xray-tracer?branch=master) [![GitHub](https://img.shields.io/github/license/opentracing-contrib/java-xray-tracer.svg)](https://opensource.org/licenses/Apache-2.0)\n\n# opentracing-java-aws-xray\nJava OpenTracing implementation backed by AWS X-Ray.\n\n**WARNING: this code is currently in beta: please test thoroughly before deploying to production, and report any issues.**\n\n## Overview\n\nThe [OpenTracing specification](https://opentracing.io) is a vendor-neutral API for instrumentation and distributed \ntracing. This library provides an implementation which is backed by the [AWS X-Ray Java SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html),\nand for the most part just provides a thin wrapper around the underlying X-Ray classes.\n\n## Using this library\n\nThe code is not yet being deployed to Maven central (we're working on that!), so you'll have to build your own version. This should be as simple as:\n\n- cloning this repository locally\n- running `mvn package` [1]\n- including the resulting JAR file in your `/lib` folder (or similar)\n\n[1] If you don't already have Maven installed, you can use the `mvnw` command (or `mvnw.cmd` for Windows) instead which uses the [Maven wrapper plugin](https://github.com/takari/maven-wrapper) to download and start the correct version of Maven.\n\n## AWS compatibility\n\n#### Integrating with AWS systems\n\nSince this library mostly just wraps the standard X-Ray classes, it *should* work seamlessly in code which makes use of\nmultiple AWS services: the standard AWS SDK will add the necessary trace headers automatically, and recover them on \nremote servers (e.g. when invoking lambda functions). However, this hasn't yet been extensively tested, so feedback\nand bug reports are very welcome!\n\n\n#### Naming conventions\n\nThe OpenTracing standard and the AWS X-Ray system each use different naming conventions for some of the same concepts \n(e.g. HTTP response codes). Since the goal of this project is to largely hide the fact that we're using X-Ray under the \nhood, and to only expose the OpenTracing API:\n\n- client code should prefer using the [OpenTracing naming conventions](https://opentracing.io/specification/conventions/) \n  for tag names (however, if you supply the X-Ray-specific names, values will still end up in the right place)\n- this library will silently convert *some* known tag names values to their X-Ray equivalents\n- X-Ray traces further subdivide tagged values into separate sub-objects for e.g. HTTP request and response data:\n  - where possible, ensure values end up in the correct place on the trace\n  - all other values are stored in the `metadata` section, under a `default` namespace if not specified\n  - see the [X-Ray Segment Documents](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html)\n    for further details\n\nThe following OpenTracing names will be translated to fit the X-Ray names:\n\n| OpenTracing tag name  | X-Ray trace name                |\n|-----------------------|---------------------------------|\n| `version`             | `service.version`               |\n| `db.instance`         | `sql.url`                       |\n| `db.statement`        | `sql.sanitized_query`           |\n| `db.type`             | `sql.database_type`             |\n| `db.user`             | `sql.user`                      |\n| `db.driver`           | `sql.driver`                    |\n| `db.version`          | `sql.version`                   |\n| `http.method`         | `http.request.method`           |\n| `http.url`            | `http.request.url`              |\n| `http.client_ip`      | `http.request.client_ip`        |\n| `http.user_agent`     | `http.request.user_agent`       |\n| `http.status_code`    | `http.response.status`          |\n| `http.content_length` | `http.response.content_length`  |\n| `foo`                 | `metadata.default.foo`          |\n| `widget.foo`          | `metadata.widget.foo`           |\n\nAdditionally, the following special tag names are defined in `AWSXRayTags` and can be used to directly modify the\nbehaviour of the underlying X-Ray trace `Entity` (NB some of these only work for `Segment`, i.e. top-level spans):\n\n|                       | Behaviour                       | `Segment` | `Subsegment` |\n|-----------------------|---------------------------------|-----------|--------------|\n| `error`               | sets the `isError()` flag       | Y         | Y            |\n| `fault`               | sets the `isFault()` flag       | Y         | Y            | \n| `throttle`            | sets the `isThrottle()` flag    | Y         | Y            |\n| `isSampled`           | sets the `isSampled()` flag     | Y         | -            |\n| `user`                | sets the `user` value           | Y         | -            |\n| `origin`              | sets the `origin` value         | Y         | -            |\n| `parentId`            | sets the `parentId` value       | Y         | Y            |\n\n#### Context injection / extraction\n\nThis library supports basic [injection and extraction of SpanContext](https://opentracing.io/specification/#inject-a-spancontext-into-a-carrier):\n\n- in most cases it is expected that this library will be used in AWS-hosted systems, and calls between AWS services\n  using the official SDK will already handle passing trace IDs across so no further work is required\n  \n- for non-AWS systems, the current `SpanContext` can be converted into e.g. a set of HTTP \n  headers using `Tracer.inject` and sent over the wire; on the other side, `Tracer.extract` can be used to convert \n  the headers back into a `SpanContext`\n  \n- for compatibility between AWS and non-AWS services, we store the trace context information in a single header `X-Amzn-Trace-Id` - see the \n  [Amazon trace header documentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) \n  for more details\n\n## Known limitations\n\nThis library does not currently provide a full implementation of the OpenTracing API: the X-Ray classes themselves \nalready provide some of the same features, and in other cases the APIs are incompatible. The following limitations \ncurrently apply:\n\n#### References\n\nOpenTracing provides for arbitrary [references between spans](https://opentracing.io/specification/#references-between-spans), \nincluding parent-child and follows-from relationships. In practice X-Ray only supports parent-child relationships, and\neach span can have at most one parent. Calls to add references of different types, or multiple parent-child relationships,\nwill generally be ignored.\n\n#### Logging\n\nOpenTracing provides methods to add [logs to the trace](https://opentracing.io/specification/#log-structured-data). \nThese methods will work as expected: structured data are stored in X-Ray metadata under a \"log\" namespace, but this\napproach isn't advised since the resulting JSON format is clunky. A better approach in AWS is to make use of \n[CloudWatch](https://aws.amazon.com/cloudwatch/).\n\n## License\n\nThis project is licensed under the [Apache 2.0](/LICENSE) License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopentracing-contrib%2Fjava-xray-tracer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopentracing-contrib%2Fjava-xray-tracer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopentracing-contrib%2Fjava-xray-tracer/lists"}