{"id":20314620,"url":"https://github.com/release-engineering/opentelemetry-ext-cli-java","last_synced_at":"2025-03-04T08:44:24.798Z","repository":{"id":63716268,"uuid":"561064149","full_name":"release-engineering/opentelemetry-ext-cli-java","owner":"release-engineering","description":"Opentelemetry context propagation for reading trace context from system environment variables, for CLI tools","archived":false,"fork":false,"pushed_at":"2023-01-16T08:41:37.000Z","size":94,"stargazers_count":0,"open_issues_count":2,"forks_count":2,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-01-14T12:48:49.965Z","etag":null,"topics":[],"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/release-engineering.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}},"created_at":"2022-11-02T21:37:57.000Z","updated_at":"2022-11-15T20:39:43.000Z","dependencies_parsed_at":"2023-02-10T02:00:25.896Z","dependency_job_id":null,"html_url":"https://github.com/release-engineering/opentelemetry-ext-cli-java","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fopentelemetry-ext-cli-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fopentelemetry-ext-cli-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fopentelemetry-ext-cli-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fopentelemetry-ext-cli-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/release-engineering","download_url":"https://codeload.github.com/release-engineering/opentelemetry-ext-cli-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241818857,"owners_count":20025210,"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-14T18:16:06.922Z","updated_at":"2025-03-04T08:44:24.774Z","avatar_url":"https://github.com/release-engineering.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\nThis is a specialized OpenTelemetry trace context propagator for command-line applications. It's is especially useful when your CLI tools are used from Jenkins pipelines with the Jenkins OpenTelemetry Plugin enabled. This plugin exposes specific environment variables to tool executions:\n\n* `TRACEPARENT`\n* `TRACESTATE`\n* `TRACE_ID`\n* `SPAN_ID`\n\nIf the value of those environment variables refer to a `file://` or `http://` URL then that will be automatically \nresolved to read the value of the referenced variable.\n\nIf your CLI tools call other services, it can be very important to consume this context so you can propagate the trace to those other services.\n\n## Example: Command-Line Interface Usage\n\nThe `OTelCLIHelper` utility class is intended to move the OpenTelemetry setup out of your way:\n\n```java\npublic static void main(String[] args)\n{\n    OTelCLIHelper.startOTel(\n        \"my-service\",\n        OTelCLIHelper.defaultSpanProcessor(\n            OTelCliHelper.defaultSpanExporter(\"http://localhost:4317\")\n        )\n    );\n\n    try\n    {\n        Span.current().setAttribute(\"input-file\", args[0]);\n        // do some cool stuff\n    }\n    finally\n    {\n        OTelCLIHelper.stopOTel();\n    }\n}\n```\n\nIf you'd like more control over the setup, you can handle it manually like this:\n\n```java\nResource resource = Resource.getDefault()\n                            .merge( Resource.create( Attributes.of( ResourceAttributes.SERVICE_NAME,\n                                                                    serviceName ) ) );\n\nSpanExporter exporter = OtlpGrpcSpanExporter.builder().setEndpoint( endpoint ).build();\nSpanProcessor processor = BatchSpanProcessor.builder(exporter).build();\nSdkTracerProvider sdkTracerProvider =\n                SdkTracerProvider.builder().addSpanProcessor( processor ).setResource( resource ).build();\n\n// NOTE the use of EnvarExtractingPropagator here\nOpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()\n                                                 .setTracerProvider( sdkTracerProvider )\n                                                 .setPropagators( ContextPropagators.create(\n                                                                 EnvarExtractingPropagator.getInstance() ) )\n                                                 .buildAndRegisterGlobal();\n\nContext parentContext = EnvarExtractingPropagator.getInstance().extract( Context.root(), null, null );\nSpan root = openTelemetry.getTracer( serviceName )\n                               .spanBuilder( \"cli-execution\" )\n                               .setParent( parentContext )\n                               .startSpan();\nroot.makeCurrent();\n```\n\n## Example: Quarkus Setup\n\nQuarkus usage may seem a little weird for a context propagator that reads trace context from environment variables. It doesn't match the typical request-driven context propagation. However, for certain use cases we use a Quarkus as a Kubernetes sidecar, and the main container is a single execution associated with a larger trace. In this very specific use case, we actually want to pull the trace context from the environment variables and IGNORE those coming from the main container.\n\nAt least for now. Maybe this is a terrible idea, and we'll erase this use case and quietly back away... \n\nTo enable this propagator in Quarkus, add the following to your `application.yaml` file:\n\n```yaml\nquarkus:\n  [...]\n\n  opentelemetry:\n    enabled: true\n    propagators:\n      - envar\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelease-engineering%2Fopentelemetry-ext-cli-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frelease-engineering%2Fopentelemetry-ext-cli-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelease-engineering%2Fopentelemetry-ext-cli-java/lists"}