{"id":20208826,"url":"https://github.com/palantir/tracing-java","last_synced_at":"2025-04-07T12:09:02.883Z","repository":{"id":37514836,"uuid":"142940399","full_name":"palantir/tracing-java","owner":"palantir","description":"Java library providing zipkin-like tracing functionality","archived":false,"fork":false,"pushed_at":"2025-04-07T10:23:20.000Z","size":2753,"stargazers_count":19,"open_issues_count":14,"forks_count":19,"subscribers_count":268,"default_branch":"develop","last_synced_at":"2025-04-07T11:29:15.145Z","etag":null,"topics":["octo-correct-managed"],"latest_commit_sha":null,"homepage":"","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/palantir.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog/3.0.0/remove-jackson-api-dep.v2.yml","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":"2018-07-31T00:05:08.000Z","updated_at":"2025-04-07T10:23:23.000Z","dependencies_parsed_at":"2023-09-28T14:08:51.826Z","dependency_job_id":"1de50957-4e2c-4622-9d28-23ecb027a7bf","html_url":"https://github.com/palantir/tracing-java","commit_stats":{"total_commits":1234,"total_committers":31,"mean_commits":"39.806451612903224","dds":"0.13047001620745546","last_synced_commit":"bc4f2093728fc0765111de221e28ab6fd26cf2b3"},"previous_names":[],"tags_count":90,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Ftracing-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Ftracing-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Ftracing-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/palantir%2Ftracing-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/palantir","download_url":"https://codeload.github.com/palantir/tracing-java/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648978,"owners_count":20972945,"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":["octo-correct-managed"],"created_at":"2024-11-14T05:37:15.109Z","updated_at":"2025-04-07T12:09:02.860Z","avatar_url":"https://github.com/palantir.png","language":"Java","funding_links":[],"categories":["分布式跟踪"],"sub_categories":[],"readme":"\u003cp align=\"right\"\u003e\n\u003ca href=\"https://autorelease.general.dmz.palantir.tech/palantir/tracing-java\"\u003e\u003cimg src=\"https://img.shields.io/badge/Perform%20an-Autorelease-success.svg\" alt=\"Autorelease\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# tracing-java [![Download](https://api.bintray.com/packages/palantir/releases/tracing-java/images/download.svg) ](https://bintray.com/palantir/releases/tracing-java/_latestVersion)\n\n[Zipkin](https://github.com/openzipkin/zipkin)-style call tracing libraries.\n\n- **com.palantir.tracing:tracing** - The key `Tracer` class, which stores trace information in a ThreadLocal.  Also includes classes for convenient integration with SLF4J and executor services.\n- **com.palantir.tracing:tracing-api** - constants and pure data objects\n- **com.palantir.tracing:tracing-jaxrs** - utilities to wrap `StreamingOutput` responses with a new trace.\n- **com.palantir.tracing:tracing-okhttp3** - `OkhttpTraceInterceptor`, which adds the appropriate headers to outgoing requests.\n- **com.palantir.tracing:tracing-jersey** - `TraceEnrichingFilter`, a jaxrs filter which reads headers from incoming requests and writes headers to outgoing responses.  A traceId is stored in the jaxrs request context under the key `com.palantir.tracing.traceId`.\n- **com.palantir.tracing:tracing-undertow** - `TracedOperationHandler`, an Undertow handler reads headers from incoming requests and writes headers to outgoing responses.\n- **com.palantir.tracing:tracing-test-utils** - JUnit classes to render traces and also allow snapshot testing them.\n\nClients and servers propagate call trace ids across JVM boundaries according to the\n[Zipkin](https://github.com/openzipkin/zipkin) specification. In particular, clients insert `X-B3-TraceId: \u003cTrace ID\u003e`\nHTTP headers into all requests which get propagated by Jetty servers into subsequent client invocations. We enhance\nthe Zipkin spec in one regard; with outgoing traces we additionally send an `X-OrigSpanId: \u003cOriginating Span ID\u003e`\nheader which enables request logs to be considered a useful subset of the trace events, even on unsampled requests.\n\n## Usage\n\nExample of how to use the `tracing` library:\n\n```groovy\n// build.gradle\ndependencies {\n  compile \"com.palantir.tracing:tracing:$version\"\n}\n```\n\n```java\ntry (CloseableTracer span = CloseableTracer.startSpan(\"do work\")) {\n    Thread.sleep(100);\n    doWork();\n}\n```\n\nAt the end of this try-with-resources block, any registered SpanObservers will be notified with a single immutable `Span` object. The above example demonstrates how to instrument chunks of code that start and finish on one thread. For cross-thread tracing, see `DetachedSpan`.\n\n## Logging with SLF4J\n\nBy default, the instrumentation forwards trace and span information through HTTP headers, but does not emit completed\nspans to a log file or to Zipkin.  Span observers are static (similar to SLF4J appenders) and can be configured as\nfollows:\n\n```java\n// Emit all completed spans to the provided span observer:\nTracer.subscribe(\"SLF4J\" /* user-defined name */, spanObserver);\n\n// No longer emit span events to SLF4J:\nTracer.unsubscribe(\"SLF4J\");\n```\nNote that span observers are static; a server typically subscribes span observers in its initialization phase.\nLibraries should never register span observers (since they can trample observers registered by consumers of the library\nwhose themselves register observers).\n\n\n## tracing-test-utils\n\nYou can set up 'snapshot testing' by adding the `@TestTracing` annotation to a test method (this requires JUnit 5).\n\n```diff\n import org.junit.jupiter.api.Test;\n import com.palantir.tracing.TestTracing;\n\n public class MyTest {\n     @Test\n+    @TestTracing(snapshot = true)\n     public void foo() {\n     }\n }\n```\n\nWhen you run this test for the first time, it will capture all spans and write them to a file `src/test/resources/tracing/MyTest/foo`, which should be checked-in to Git.  This file will be used as a 'golden master', and all future runs will be compared against it.\n\n```\n{\"traceId\":\"7e1014caf8a7278e\",\"parentSpanId\":\"972f9b3a09431b67\",\"spanId\":\"f701b7f815176ec2\",\"operation\":\"healthcheck: SERVICE_DEPENDENCY\",\"startTimeMicroSeconds\":1566902887342052,\"durationNanoSeconds\":20377272,\"metadata\":{}}\n...\n```\n\nIf your production code changes and starts producing different spans, the test will fail and render two HTML visualizations: `expected.html` and `actual.html`.\n\nSnapshot-testing is not available in JUnit4, but you can still see a HTML visualization of your traces using the `RenderTracingRule`:\n\n```diff\n import org.junit.Test;\n import com.palantir.tracing.RenderTracingRule;\n\n public class MyTest {\n\n+    @Rule\n+    public final RenderTracingRule rule = new RenderTracingRule();\n\n     @Test\n     public void foo() {\n     }\n }\n```\n\n## License\n\nThis repository is made available under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalantir%2Ftracing-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpalantir%2Ftracing-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpalantir%2Ftracing-java/lists"}