{"id":13511819,"url":"https://github.com/openzipkin/zipkin","last_synced_at":"2026-01-12T00:47:02.908Z","repository":{"id":3517996,"uuid":"4576305","full_name":"openzipkin/zipkin","owner":"openzipkin","description":"Zipkin is a distributed tracing system","archived":false,"fork":false,"pushed_at":"2025-04-27T20:30:55.000Z","size":77273,"stargazers_count":17182,"open_issues_count":169,"forks_count":3107,"subscribers_count":684,"default_branch":"master","last_synced_at":"2025-05-05T14:09:19.556Z","etag":null,"topics":["distributed-tracing","observability","openzipkin","tracing","zipkin"],"latest_commit_sha":null,"homepage":"https://zipkin.io/","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/openzipkin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-06-06T18:26:16.000Z","updated_at":"2025-05-05T11:31:01.000Z","dependencies_parsed_at":"2023-02-10T14:46:26.861Z","dependency_job_id":"8b52f70b-9695-4394-8b46-a45ac95cfc43","html_url":"https://github.com/openzipkin/zipkin","commit_stats":{"total_commits":2735,"total_committers":138,"mean_commits":"19.818840579710145","dds":0.6994515539305302,"last_synced_commit":"ea2da727557ae2cc275fdf5d15f79ceb14b275db"},"previous_names":["apache/incubator-zipkin","twitter/zipkin"],"tags_count":235,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openzipkin","download_url":"https://codeload.github.com/openzipkin/zipkin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252542086,"owners_count":21764908,"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":["distributed-tracing","observability","openzipkin","tracing","zipkin"],"created_at":"2024-08-01T03:01:12.258Z","updated_at":"2026-01-12T00:47:02.825Z","avatar_url":"https://github.com/openzipkin.png","language":"Java","readme":"# zipkin\n\n[![Gitter chat](http://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/openzipkin/zipkin)\n[![Build Status](https://github.com/openzipkin/zipkin/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/openzipkin/zipkin/actions?query=workflow%3Atest+branch%3Amaster)\n[![Maven Central](https://img.shields.io/maven-central/v/io.zipkin/zipkin-server.svg)](https://search.maven.org/search?q=g:io.zipkin%20AND%20a:zipkin-server)\n\n[Zipkin](https://zipkin.io) is a distributed tracing system. It helps gather\ntiming data needed to troubleshoot latency problems in service architectures.\nFeatures include both the collection and lookup of this data.\n\nIf you have a trace ID in a log file, you can jump directly to it. Otherwise,\nyou can query based on attributes such as service, operation name, tags and\nduration. Some interesting data will be summarized for you, such as the\npercentage of time spent in a service, and whether operations failed.\n\n\u003cimg src=\"https://zipkin.io/public/img/web-screenshot.png\" alt=\"Trace view screenshot\" /\u003e\n\nThe Zipkin UI also presents a dependency diagram showing how many traced\nrequests went through each application. This can be helpful for identifying\naggregate behavior including error paths or calls to deprecated services.\n\n\u003cimg src=\"https://zipkin.io/public/img/dependency-graph.png\" alt=\"Dependency graph screenshot\" /\u003e\n\nApplication’s need to be “instrumented” to report trace data to Zipkin. This\nusually means configuration of a [tracer or instrumentation library](https://zipkin.io/pages/tracers_instrumentation.html). The most\npopular ways to report data to Zipkin are via http or Kafka, though many other\noptions exist, such as Apache ActiveMQ, gRPC, RabbitMQ and Apache Pulsar. The data served to\nthe UI is stored in-memory, or persistently with a supported backend such as\nApache Cassandra or Elasticsearch.\n\n## Quick-start\n\nThe quickest way to get started is to fetch the [latest released server](https://search.maven.org/remote_content?g=io.zipkin\u0026a=zipkin-server\u0026v=LATEST\u0026c=exec) as a self-contained\nexecutable jar. Note that the Zipkin server requires minimum JRE 17+. For example:\n\n```bash\ncurl -sSL https://zipkin.io/quickstart.sh | bash -s\njava -jar zipkin.jar\n```\n\nYou can also start Zipkin via Docker.\n```bash\n# Note: this is mirrored as ghcr.io/openzipkin/zipkin\ndocker run -d -p 9411:9411 openzipkin/zipkin\n```\n\nOnce the server is running, you can view traces with the Zipkin UI at http://localhost:9411/zipkin.\n\nIf your applications aren't sending traces, yet, configure them with [Zipkin instrumentation](https://zipkin.io/pages/tracers_instrumentation) or try one of our [examples](https://github.com/openzipkin?utf8=%E2%9C%93\u0026q=example).\n\nCheck out the [`zipkin-server`](zipkin-server/README.md) documentation for configuration details, or [Docker examples](docker/examples) for how to use docker-compose.\n\n### Zipkin Slim\n\nThe slim build of Zipkin is smaller and starts faster. It supports in-memory and Elasticsearch storage, but doesn't support messaging transports like Kafka or RabbitMQ. If these constraints match your needs, you can try slim like below:\n\nRunning via Java:\n```bash\ncurl -sSL https://zipkin.io/quickstart.sh | bash -s io.zipkin:zipkin-server:LATEST:slim zipkin.jar\njava -jar zipkin.jar\n```\n\nRunning via Docker:\n```bash\n# Note: this is mirrored as ghcr.io/openzipkin/zipkin-slim\ndocker run -d -p 9411:9411 openzipkin/zipkin-slim\n```\n\nRunning via [Homebrew](https://formulae.brew.sh/formula/zipkin):\n```bash\nbrew install zipkin\n# to run in foreground\nzipkin\n# to run in background\nbrew services start zipkin\n```\n\n## Core Library\nThe [core library](zipkin/src/main/java/zipkin2) is used by both Zipkin instrumentation and the Zipkin server.\n\nThis includes built-in codec for Zipkin's v1 and v2 json formats. A direct dependency on gson\n(json library) is avoided by minifying and repackaging classes used. The result is a 155k jar which\nwon't conflict with any library you use.\n\nEx.\n```java\n// All data are recorded against the same endpoint, associated with your service graph\nlocalEndpoint = Endpoint.newBuilder().serviceName(\"tweetie\").ip(\"192.168.0.1\").build()\nspan = Span.newBuilder()\n    .traceId(\"d3d200866a77cc59\")\n    .id(\"d3d200866a77cc59\")\n    .name(\"targz\")\n    .localEndpoint(localEndpoint)\n    .timestamp(epochMicros())\n    .duration(durationInMicros)\n    .putTag(\"compression.level\", \"9\");\n\n// Now, you can encode it as json\nbytes = SpanBytesEncoder.JSON_V2.encode(span);\n```\n\nNote: The above is just an example, most likely you'll want to use an existing tracing library like [Brave](https://github.com/openzipkin/brave)\n\n### Core Library Requires Java 8+\n\nThe minimum Java language level of the core library is 8. This helps support those writing agent\ninstrumentation. Version 2.x was the last to support Java 6.\n\n*Note*: [zipkin-reporter-brave](https://github.com/openzipkin/zipkin-reporter-java/blob/master/brave/README.md)\ndoes not use this library. So, [brave](https://github.com/openzipkin/brave) still supports Java 6.\n\n## Storage Component\nZipkin includes a [StorageComponent](zipkin/src/main/java/zipkin2/storage/StorageComponent.java), used to store and query spans and\ndependency links. This is used by the server and those making collectors, or span reporters.\nFor this reason, storage components have minimal dependencies, though require Java 17+.\n\nEx.\n```java\n// this won't create network connections\nstorage = ElasticsearchStorage.newBuilder()\n                              .hosts(asList(\"http://myelastic:9200\")).build();\n\n// prepare a call\ntraceCall = storage.spanStore().getTrace(\"d3d200866a77cc59\");\n\n// execute it synchronously or asynchronously\ntrace = traceCall.execute();\n\n// clean up any sessions, etc\nstorage.close();\n```\n\n### In-Memory\nThe [InMemoryStorage](zipkin-server#in-memory-storage) component is packaged in zipkin's core library. It\nis neither persistent, nor viable for realistic work loads. Its purpose\nis for testing, for example starting a server on your laptop without any\ndatabase needed.\n\n### Cassandra\nThe [Cassandra](zipkin-server#cassandra-storage) component uses Cassandra\n3.11.3+ features, but is tested against the latest patch of Cassandra 4.1.\n\nThis is the second generation of our Cassandra schema. It stores spans\nusing UDTs, such that they appear like Zipkin v2 json in cqlsh. It is\ndesigned for scale, and uses a combination of SASI and manually\nimplemented indexes to make querying larger data more performant.\n\nNote: This store requires a [job to aggregate](https://github.com/openzipkin/zipkin-dependencies) dependency links.\n\n### Elasticsearch\nThe [Elasticsearch](zipkin-server#elasticsearch-storage) component uses\nElasticsearch 5+ features, but is tested against Elasticsearch 7-8.x and\nOpenSearch 2.x.\n\nIt stores spans as Zipkin v2 json so that integration with other tools is\nstraightforward. To help with scale, this uses a combination of custom\nand manually implemented indexing.\n\nNote: This store requires a [spark job](https://github.com/openzipkin/zipkin-dependencies) to aggregate dependency links.\n\n### Disabling search\nThe following API endpoints provide search features, and are enabled by\ndefault. Search primarily allows the trace list screen of the UI operate.\n* `GET /services` - Distinct Span.localServiceName\n* `GET /remoteServices?serviceName=X` - Distinct Span.remoteServiceName by Span.localServiceName\n* `GET /spans?serviceName=X` - Distinct Span.name by Span.localServiceName\n* `GET /autocompleteKeys` - Distinct keys of Span.tags subject to configurable whitelist\n* `GET /autocompleteValues?key=X` - Distinct values of Span.tags by key\n* `GET /traces` - Traces matching a query possibly including the above criteria\n\n\nWhen search is disabled, traces can only be retrieved by ID\n(`GET /trace/{traceId}`). Disabling search is only viable when there is\nan alternative way to find trace IDs, such as logs. Disabling search can\nreduce storage costs or increase write throughput.\n\n`StorageComponent.Builder.searchEnabled(false)` is implied when a zipkin\nis run with the env variable `SEARCH_ENABLED=false`.\n\n### Legacy (v1) components\nThe following components are no longer encouraged, but exist to help aid\ntransition to supported ones. These are indicated as \"v1\" as they use\ndata layouts based on Zipkin's V1 Thrift model, as opposed to the\nsimpler v2 data model currently used.\n\n#### MySQL\nThe [MySQL v1](zipkin-storage/mysql-v1) component uses MySQL 5.6+\nfeatures, but is tested against MariaDB 10.11.\n\nThe schema was designed to be easy to understand and get started with;\nit was not designed for performance. Ex spans fields are columns, so\nyou can perform ad-hoc queries using SQL. However, this component has\n[known performance issues](https://github.com/openzipkin/zipkin/issues/1233): queries will eventually take seconds to return\nif you put a lot of data into it.\n\nThis store does not require a [job to aggregate](https://github.com/openzipkin/zipkin-dependencies) dependency links.\nHowever, running the job will improve performance of dependencies\nqueries.\n\n## Running the server from source\nThe [Zipkin server](zipkin-server) receives spans via HTTP POST and respond to queries\nfrom its UI. It can also run collectors, such as RabbitMQ or Kafka.\n\nTo run the server from the currently checked out source, enter the\nfollowing. JDK 17+ is required to compile the source.\n```bash\n# Build the server and also make its dependencies\n$ ./mvnw -q --batch-mode -DskipTests --also-make -pl zipkin-server clean install\n# Run the server\n$ java -jar ./zipkin-server/target/zipkin-server-*exec.jar\n```\n\n## Artifacts\nServer artifacts are under the maven group id `io.zipkin`\nLibrary artifacts are under the maven group id `io.zipkin.zipkin2`\n\n### Library Releases\nReleases are at [Sonatype](https://oss.sonatype.org/content/repositories/releases) and [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.zipkin%22)\n\n### Library Snapshots\nSnapshots are uploaded to [Sonatype](https://oss.sonatype.org/content/repositories/snapshots) after\ncommits to master.\n\n### Docker Images\nReleased versions of zipkin-server are published to Docker Hub as `openzipkin/zipkin` and GitHub\nContainer Registry as `ghcr.io/openzipkin/zipkin`. See [docker](docker) for details.\n\n### Helm Charts\nHelm charts are available via `helm repo add zipkin https://zipkin.io/zipkin-helm`.\nSee [zipkin-helm](https://github.com/openzipkin/zipkin-helm) for details.\n\n### Javadocs\nhttps://zipkin.io/zipkin contains versioned folders with JavaDocs published on each (non-PR) build, as well\nas releases.\n","funding_links":[],"categories":["7. Storage","Java","APM","微服务生态","Tracing \u0026 Profiling","Software/System","others","应用分析与监控","III. Network and Integration","Distributed Tracing","Packages","Profilers","Observability"],"sub_categories":["Tracing","康威定律","Develop","10. Integratin with API","Zipkin","Tools","Distributed Tracing"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzipkin%2Fzipkin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzipkin%2Fzipkin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzipkin%2Fzipkin/lists"}