{"id":28434971,"url":"https://github.com/cosmicmind/opentelemetry-xray","last_synced_at":"2025-09-23T13:42:21.402Z","repository":{"id":276710831,"uuid":"930028484","full_name":"CosmicMind/opentelemetry-xray","owner":"CosmicMind","description":"A library for AWS X‑Ray distributed tracing using OpenTelemetry.","archived":false,"fork":false,"pushed_at":"2025-06-19T08:00:56.000Z","size":39,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"release","last_synced_at":"2025-06-26T09:49:56.175Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/CosmicMind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2025-02-09T23:42:03.000Z","updated_at":"2025-05-31T06:32:49.000Z","dependencies_parsed_at":null,"dependency_job_id":"a666287b-879f-4c6d-985c-3d6f59f1ceea","html_url":"https://github.com/CosmicMind/opentelemetry-xray","commit_stats":null,"previous_names":["cosmicmind/opentelemetry-xray"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/CosmicMind/opentelemetry-xray","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosmicMind%2Fopentelemetry-xray","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosmicMind%2Fopentelemetry-xray/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosmicMind%2Fopentelemetry-xray/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosmicMind%2Fopentelemetry-xray/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CosmicMind","download_url":"https://codeload.github.com/CosmicMind/opentelemetry-xray/tar.gz/refs/heads/release","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosmicMind%2Fopentelemetry-xray/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262043894,"owners_count":23249727,"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":"2025-06-05T19:42:00.481Z","updated_at":"2025-09-23T13:42:21.384Z","avatar_url":"https://github.com/CosmicMind.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opentelemetry-xray\n\nopentelemetry-xray is a Rust library that provides a flexible interface for AWS X‑Ray distributed tracing using OpenTelemetry. It simplifies the integration of AWS X‑Ray with your applications by setting up a global tracer provider, mapping tracing contexts into AWS X‑Ray–compatible formats, and supporting rich span information such as annotations, metadata, exceptions, and HTTP context.\n\n## Features\n\n- **AWS X‑Ray Integration:**\n    - Formats trace IDs according to AWS X‑Ray standards.\n    - Transforms the standard `traceparent` header into the AWS X‑Ray header (`x-amzn-trace-id`).\n    - Exports span data as JSON segments that AWS X‑Ray can understand.\n- **OpenTelemetry \u0026 Tracing Support:**\n    - Leverages the robust OpenTelemetry ecosystem.\n    - Integrates seamlessly with the `tracing` crate for structured logging and span management.\n- **Span Enrichment:**\n    - **Annotations:** Indexed fields (e.g. use the prefix `annotation.`) for filtering and searching.\n    - **Metadata:** Additional non-indexed data (using the `metadata.` prefix).\n    - **Exceptions:** Detailed error information (with keys like `exception.type` and `exception.message`).\n    - **HTTP Context:** Record HTTP request and response details (using keys such as `http.request.method` and `http.response.status`).\n\n\u003e **Note:** In these examples we show keys as dot‑separated (e.g. `annotation.otel.kind`) without extra quotation marks. In your actual Rust code, if a field name isn't a valid identifier (because it includes a period), you may need to use a string literal (for example, `\"annotation.otel.kind\" = \"server\"`)—the important part is that the exported key appears as `annotation.otel.kind` (and similarly for `http.request`, `http.response`, etc).\n\n## Installation\n\nAdd the following to your `Cargo.toml`:\n\n```toml\n[dependencies]\nopentelemetry-xray = \"0.1.5\"\nopentelemetry = { version = \"0.29.0\", features = [\"trace\"] }\ntracing = \"0.1.41\"\ntracing-subscriber = { version = \"0.3.19\", features = [\"env-filter\", \"json\"] }\n```\n\n## Quick Start\n\nInitialize your telemetry and create a span enriched with annotations, metadata, and exception details:\n\n```rust\nuse opentelemetry_xray::{Telemetry, TelemetryConfig};\nuse tracing::{info_span, error, Instrument};\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let config = TelemetryConfig {\n        service_name: \"my-service\".into(),\n        service_version: env!(\"CARGO_PKG_VERSION\").into(),\n        deployment_env: \"production\".into(),\n        log_level: \"info\".into(),\n    };\n    \n    // Initialize the propagator, tracer provider, and subscriber.\n    let telemetry = Telemetry::init(config)?;\n    \n    // Create a span with enriched attributes. In these examples, we conceptually use keys like:\n    //   annotation.user_id, metadata.request_id, http.request.method, etc.\n    let span = info_span!(\n        main_operation,\n        annotation.user_id = 42,\n        metadata.request_id = \"abc123\",\n        // HTTP-related attributes:\n        http.request.method = \"GET\",\n        http.request.url = \"https://example.com/api\"\n    );\n    \n    async {\n        if let Err(err) = do_something().await {\n            // Record exception details:\n            error!(\n                exception.type = \"OperationError\",\n                exception.message = %err,\n                \"Operation failed\"\n            );\n        }\n    }\n    .instrument(span)\n    .await;\n    \n    telemetry.shutdown();\n    \n    Ok(())\n}\n\nasync fn do_something() -\u003e Result\u003c(), \u0026'static str\u003e {\n    Err(\"Something went wrong\")\n}\n```\n\n## Using Annotations, Metadata, and Exceptions\n\n### Annotations\n\nAnnotations are meant to be indexed and are useful for filtering and searching in AWS X‑Ray. Specify annotation attributes using the `annotation.` prefix:\n\n```rust\nuse tracing::info_span;\n\nlet span = info_span!(\n    processing_order,\n    annotation.order_id = 1001,\n    annotation.priority = \"high\"\n);\n```\n\n### Metadata\n\nMetadata provides additional context but is not indexed. Use the `metadata.` prefix:\n\n```rust\nlet span = info_span!(\n    user_session,\n    metadata.session_id = \"xyz789\",\n    metadata.user_agent = \"Mozilla/5.0\"\n);\n```\n\n### Exception Reporting\n\nWhen errors occur, capture detailed error information by using the `exception.` prefix:\n\n```rust\nuse tracing::error;\n\nlet err = \"Null Pointer Exception\";\nerror!(\n    exception.type = \"NullPointerException\",\n    exception.message = err,\n    \"An error occurred\"\n);\n```\n\n## HTTP Integration\n\n### Server-side Tracing\n\nExtract incoming trace contexts from HTTP requests and create spans enriched with HTTP attributes:\n\n```rust\nuse axum::{Router, routing::get};\nuse tower_http::trace::TraceLayer;\nuse opentelemetry_xray::{extract_headers, Telemetry};\nuse axum::http::Request;\nuse axum::body::Body;\n\nasync fn handler() {\n    // Your request handling logic.\n}\n\nasync fn build_router() -\u003e Router {\n    Router::new()\n        .route(\"/\", get(handler))\n        .layer(\n            TraceLayer::new_for_http().make_span_with(|request: \u0026Request\u003cBody\u003e| {\n                let span = tracing::info_span!(\n                    http_request,\n                    http.request.method = ?request.method(),\n                    http.request.url = ?request.uri()\n                );\n                // Extract and set the incoming trace context:\n                let parent_context = extract_headers(request.headers());\n                span.set_parent(parent_context);\n                span\n            })\n        )\n}\n```\n\n### Client-side Tracing\n\nInject the current trace context into outgoing HTTP requests so downstream services continue the distributed trace:\n\n```rust\nuse reqwest::Client;\nuse http::HeaderMap;\nuse opentelemetry_xray::inject_headers;\n\nasync fn make_request(client: \u0026Client, url: \u0026str) -\u003e Result\u003c(), reqwest::Error\u003e {\n    let mut headers = HeaderMap::new();\n    // Inject the current OpenTelemetry context (this converts the standard\n    // `traceparent` header to the AWS X‑Ray header, e.g. `x-amzn-trace-id`).\n    inject_headers(\u0026mut headers);\n    \n    client.get(url)\n        .headers(headers)\n        .send()\n        .await?;\n    \n    Ok(())\n}\n```\n\n## Configuration Options\n\nConfigure telemetry using the `TelemetryConfig` struct:\n\n```rust\nlet config = TelemetryConfig {\n    service_name: \"my-service\".into(),\n    service_version: env!(\"CARGO_PKG_VERSION\").into(),\n    deployment_env: \"production\".into(),\n    log_level: \"info\".into(),\n};\n```\n\n## Best Practices\n\n1. **Initialization:**\n    - Use `Telemetry::init()` for a standardized setup of the propagator, tracer provider, and subscriber.\n    - Always call `telemetry.shutdown()` at application exit to ensure all spans are flushed.\n2. **Span Enrichment:**\n    - Use `tracing` macros (e.g., `info_span!`, `error!`) to create spans.\n    - Use meaningful dot‑separated keys (e.g., `annotation.`, `metadata.`, `http.request.`, `exception.`) to indicate the purpose of each attribute.\n3. **Error Handling:**\n    - Capture and report exceptions using the designated keys to facilitate troubleshooting.\n4. **HTTP Instrumentation:**\n    - For server-side tracing, extract HTTP headers via `extract_headers`.\n    - For client-side requests, inject the trace context with `inject_headers`.\n\n## Testing\n\nRun the test suite:\n\n```bash\ncargo test\n```\n\n## License\n\nThis project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request with your improvements or bug fixes.\n\n## Related Projects\n\n- [OpenTelemetry Rust](https://github.com/open-telemetry/opentelemetry-rust)\n- [AWS X-Ray](https://aws.amazon.com/xray/)\n- [tracing](https://github.com/tokio-rs/tracing)\n\n## Support\n\nFor issues and feature requests, please use the [GitHub issue tracker](https://github.com/cosmicmind/opentelemetry-xray/issues).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosmicmind%2Fopentelemetry-xray","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcosmicmind%2Fopentelemetry-xray","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosmicmind%2Fopentelemetry-xray/lists"}