{"id":13657583,"url":"https://github.com/census-instrumentation/opencensus-java","last_synced_at":"2025-04-24T01:32:28.930Z","repository":{"id":10214879,"uuid":"64431348","full_name":"census-instrumentation/opencensus-java","owner":"census-instrumentation","description":"A stats collection and distributed tracing framework","archived":true,"fork":false,"pushed_at":"2023-07-05T20:50:24.000Z","size":7569,"stargazers_count":672,"open_issues_count":113,"forks_count":201,"subscribers_count":69,"default_branch":"master","last_synced_at":"2024-08-02T05:07:13.660Z","etag":null,"topics":["cloud","dapper","distributed-tracing","java","metrics","monitoring","opencensus","prometheus","signalfx","stackdriver","stats","trace","tracing","zipkin"],"latest_commit_sha":null,"homepage":"https://opencensus.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/census-instrumentation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2016-07-28T22:10:03.000Z","updated_at":"2024-05-31T08:12:05.000Z","dependencies_parsed_at":"2022-08-07T21:00:03.890Z","dependency_job_id":null,"html_url":"https://github.com/census-instrumentation/opencensus-java","commit_stats":{"total_commits":1950,"total_committers":70,"mean_commits":"27.857142857142858","dds":0.6676923076923077,"last_synced_commit":"baa68680b19040ff7739e314a2422a25cf41e27a"},"previous_names":["google/census-java","google/instrumentation-java"],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/census-instrumentation%2Fopencensus-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/census-instrumentation%2Fopencensus-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/census-instrumentation%2Fopencensus-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/census-instrumentation%2Fopencensus-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/census-instrumentation","download_url":"https://codeload.github.com/census-instrumentation/opencensus-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223941094,"owners_count":17228954,"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":["cloud","dapper","distributed-tracing","java","metrics","monitoring","opencensus","prometheus","signalfx","stackdriver","stats","trace","tracing","zipkin"],"created_at":"2024-08-02T05:00:45.779Z","updated_at":"2024-11-10T10:31:40.178Z","avatar_url":"https://github.com/census-instrumentation.png","language":"Java","readme":"\u003e **Warning**\n\u003e\n\u003e OpenCensus and OpenTracing have merged to form [OpenTelemetry](https://opentelemetry.io), which serves as the next major version of OpenCensus and OpenTracing.\n\u003e\n\u003e OpenTelemetry has now reached feature parity with OpenCensus, with tracing and metrics SDKs available in .NET, Golang, Java, NodeJS, and Python. **All OpenCensus Github repositories, except [census-instrumentation/opencensus-python](https://github.com/census-instrumentation/opencensus-python), will be archived on July 31st, 2023**. We encourage users to migrate to OpenTelemetry by this date.\n\u003e\n\u003e To help you gradually migrate your instrumentation to OpenTelemetry, bridges are available in Java, Go, Python, and JS. [**Read the full blog post to learn more**](https://opentelemetry.io/blog/2023/sunsetting-opencensus/).\n\n# OpenCensus - A stats collection and distributed tracing framework\n[![Gitter chat][gitter-image]][gitter-url]\n[![Maven Central][maven-image]][maven-url]\n[![Javadocs][javadoc-image]][javadoc-url]\n[![Build Status][travis-image]][travis-url]\n[![Windows Build Status][appveyor-image]][appveyor-url]\n[![Coverage Status][codecov-image]][codecov-url]\n\n\u003e :exclamation: The [opencensus-contrib-log-correlation-log4j2](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/log_correlation/stackdriver)\n\u003e Java client library  is part of the OpenCensus project.\n\u003e [CVE-2021-44228](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-44228) \n\u003e and [CVE-2021-45046](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2021-45046) disclosed\n\u003e security vulnerabilities in the Apache Log4j 2 version 2.15 or below. The recent version\n\u003e v0.28.3 depends on Log4j 2.11.1. A number of previous versions also depend on vulnerable \n\u003e Log4j versions.\n\u003e \n\u003e :exclamation: We merged several fixes and published a release that depends on a safe version of \n\u003e Log4j (2.16). **We strongly encourage customers who depend on the \n\u003e opencensus-contrib-log-correlation-log4j2 library to upgrade to the latest \n\u003e release [(v0.30.0)](https://repo1.maven.org/maven2/io/opencensus/opencensus-contrib-log-correlation-log4j2/0.30.0/).**\n\nOpenCensus is a toolkit for collecting application performance and behavior data. It currently\nincludes 3 apis: stats, tracing and tags.\n\nThe library is in [Beta](#versioning) stage and APIs are expected to be mostly stable.\n\nPlease join [gitter](https://gitter.im/census-instrumentation/Lobby) for help or feedback on this\nproject.\n\n**OpenCensus and OpenTracing have merged to form OpenTelemetry, which serves as the next major version of OpenCensus and OpenTracing. OpenTelemetry will offer backwards compatibility with existing OpenCensus integrations, and we will continue to make security patches to existing OpenCensus libraries for two years. Read more about the merger [here](https://medium.com/opentracing/a-roadmap-to-convergence-b074e5815289).**\n\n## OpenCensus Quickstart for Libraries\n\nIntegrating OpenCensus with a new library means recording stats or traces and propagating context.\nFor application integration please see [Quickstart for Applications](https://github.com/census-instrumentation/opencensus-java#quickstart-for-applications).\n\nThe full quick start example can also be found on the [OpenCensus website](https://opencensus.io/quickstart/java/).\n\n### Add the dependencies to your project\n\nFor Maven add to your `pom.xml`:\n```xml\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.opencensus\u003c/groupId\u003e\n    \u003cartifactId\u003eopencensus-api\u003c/artifactId\u003e\n    \u003cversion\u003e0.30.0\u003c/version\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nFor Gradle add to your dependencies:\n```groovy\ncompile 'io.opencensus:opencensus-api:0.30.0'\n```\n\n### Hello \"OpenCensus\" trace events\n\nHere's an example of creating a Span and record some trace annotations. Notice that recording the\nannotations is possible because we propagate scope. 3rd parties libraries like SLF4J can integrate\nthe same way.\n\n```java\nimport io.opencensus.common.Scope;\nimport io.opencensus.trace.Tracer;\nimport io.opencensus.trace.Tracing;\nimport io.opencensus.trace.samplers.Samplers;\n\npublic final class MyClassWithTracing {\n  private static final Tracer tracer = Tracing.getTracer();\n\n  public static void doWork() {\n    // Create a child Span of the current Span. Always record events for this span and force it to\n    // be sampled. This makes it easier to try out the example, but unless you have a clear use\n    // case, you don't need to explicitly set record events or sampler.\n    try (Scope ss =\n        tracer\n            .spanBuilder(\"MyChildWorkSpan\")\n            .setRecordEvents(true)\n            .setSampler(Samplers.alwaysSample())\n            .startScopedSpan()) {\n      doInitialWork();\n      tracer.getCurrentSpan().addAnnotation(\"Finished initial work\");\n      doFinalWork();\n    }\n  }\n\n  private static void doInitialWork() {\n    // ...\n    tracer.getCurrentSpan().addAnnotation(\"Important.\");\n    // ...\n  }\n\n  private static void doFinalWork() {\n    // ...\n    tracer.getCurrentSpan().addAnnotation(\"More important.\");\n    // ...\n  }\n}\n```\n\n### Hello \"OpenCensus\" stats events\n\nHere's an example on\n * defining TagKey, Measure and View,\n * registering a view,\n * putting TagKey and TagValue into a scoped TagContext,\n * recording stats against current TagContext,\n * getting ViewData.\n\n \nFor the complete example, see\n[here](https://github.com/census-instrumentation/opencensus-java/blob/master/examples/src/main/java/io/opencensus/examples/helloworld/QuickStart.java).\n\n```java\nimport io.opencensus.common.Scope;\nimport io.opencensus.stats.Aggregation;\nimport io.opencensus.stats.BucketBoundaries;\nimport io.opencensus.stats.Measure.MeasureLong;\nimport io.opencensus.stats.Stats;\nimport io.opencensus.stats.StatsRecorder;\nimport io.opencensus.stats.View;\nimport io.opencensus.stats.ViewData;\nimport io.opencensus.stats.ViewManager;\nimport io.opencensus.tags.TagKey;\nimport io.opencensus.tags.TagValue;\nimport io.opencensus.tags.Tagger;\nimport io.opencensus.tags.Tags;\nimport java.util.Arrays;\nimport java.util.Collections;\n\npublic final class MyClassWithStats {\n  private static final Tagger tagger = Tags.getTagger();\n  private static final ViewManager viewManager = Stats.getViewManager();\n  private static final StatsRecorder statsRecorder = Stats.getStatsRecorder();\n\n  // frontendKey allows us to break down the recorded data\n  private static final TagKey FRONTEND_KEY = TagKey.create(\"myorg_keys_frontend\");\n\n  // videoSize will measure the size of processed videos.\n  private static final MeasureLong VIDEO_SIZE =\n      MeasureLong.create(\"my.org/measure/video_size\", \"size of processed videos\", \"By\");\n\n  // Create view to see the processed video size distribution broken down by frontend.\n  // The view has bucket boundaries (0, 256, 65536) that will group measure values into\n  // histogram buckets.\n  private static final View.Name VIDEO_SIZE_VIEW_NAME = View.Name.create(\"my.org/views/video_size\");\n  private static final View VIDEO_SIZE_VIEW =\n      View.create(\n          VIDEO_SIZE_VIEW_NAME,\n          \"processed video size over time\",\n          VIDEO_SIZE,\n          Aggregation.Distribution.create(\n              BucketBoundaries.create(Arrays.asList(0.0, 256.0, 65536.0))),\n          Collections.singletonList(FRONTEND_KEY));\n\n  public static void initialize() {\n    // ...\n    viewManager.registerView(VIDEO_SIZE_VIEW);\n  }\n\n  public static void processVideo() {\n    try (Scope scopedTags =\n        tagger\n            .currentBuilder()\n            .put(FRONTEND_KEY, TagValue.create(\"mobile-ios9.3.5\"))\n            .buildScoped()) {\n      // Processing video.\n      // ...\n\n      // Record the processed video size.\n      statsRecorder.newMeasureMap().put(VIDEO_SIZE, 25648).record();\n    }\n  }\n\n  public static void printStats() {\n    ViewData viewData = viewManager.getView(VIDEO_SIZE_VIEW_NAME);\n    System.out.println(\n        String.format(\"Recorded stats for %s:\\n %s\", VIDEO_SIZE_VIEW_NAME.asString(), viewData));\n  }\n}\n```\n\n## OpenCensus Quickstart for Applications\n\nBesides recording tracing/stats events the application also need to link the implementation,\nsetup exporters, and debugging [Z-Pages](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/zpages).\n\n### Add the dependencies to your project\n\nFor Maven add to your `pom.xml`:\n```xml\n\u003cdependencies\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.opencensus\u003c/groupId\u003e\n    \u003cartifactId\u003eopencensus-api\u003c/artifactId\u003e\n    \u003cversion\u003e0.30.0\u003c/version\u003e\n  \u003c/dependency\u003e\n  \u003cdependency\u003e\n    \u003cgroupId\u003eio.opencensus\u003c/groupId\u003e\n    \u003cartifactId\u003eopencensus-impl\u003c/artifactId\u003e\n    \u003cversion\u003e0.30.0\u003c/version\u003e\n    \u003cscope\u003eruntime\u003c/scope\u003e\n  \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nFor Gradle add to your dependencies:\n```groovy\ncompile 'io.opencensus:opencensus-api:0.30.0'\nruntime 'io.opencensus:opencensus-impl:0.30.0'\n```\n\n### How to setup exporters?\n\n#### Trace exporters\n* [Instana][TraceExporterInstana]\n* [Jaeger][TraceExporterJaeger]\n* [Logging][TraceExporterLogging]\n* [Stackdriver][TraceExporterStackdriver]\n* [Zipkin][TraceExporterZipkin]\n\n#### Stats exporters\n* [Stackdriver][StatsExporterStackdriver]\n* [SignalFx][StatsExporterSignalFx]\n* [Prometheus][StatsExporterPrometheus]\n\n### How to setup debugging Z-Pages?\n\nIf the application owner wants to export in-process tracing and stats data via HTML debugging pages\nsee this [link](https://github.com/census-instrumentation/opencensus-java/tree/master/contrib/zpages#quickstart).\n\n## Versioning\n  \nThis library follows [Semantic Versioning][semver].\n  \n**GA**: Libraries defined at a GA quality level are stable, and will not introduce \nbackwards-incompatible changes in any minor or patch releases. We will address issues and requests \nwith the highest priority. If we were to make a backwards-incompatible changes on an API, we will \nfirst mark the existing API as deprecated and keep it for 18 months before removing it.\n  \n**Beta**: Libraries defined at a Beta quality level are expected to be mostly stable and we're \nworking towards their release candidate. We will address issues and requests with a higher priority.\nThere may be backwards incompatible changes in a minor version release, though not in a patch \nrelease. If an element is part of an API that is only meant to be used by exporters or other \nopencensus libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18 \nmonths before removing it, if possible.\n\n[travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master\n[travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java\n[appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true\n[appveyor-url]: https://ci.appveyor.com/project/opencensusjavateam/opencensus-java/branch/master\n[javadoc-image]: https://www.javadoc.io/badge/io.opencensus/opencensus-api.svg\n[javadoc-url]: https://www.javadoc.io/doc/io.opencensus/opencensus-api\n[maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-api/badge.svg\n[maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-api\n[gitter-image]: https://badges.gitter.im/census-instrumentation/lobby.svg\n[gitter-url]: https://gitter.im/census-instrumentation/lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\n[codecov-image]: https://codecov.io/gh/census-instrumentation/opencensus-java/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/census-instrumentation/opencensus-java/branch/master/\n[semver]: http://semver.org/\n[TraceExporterInstana]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/instana#quickstart\n[TraceExporterJaeger]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/jaeger#quickstart\n[TraceExporterLogging]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/logging#quickstart\n[TraceExporterStackdriver]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/stackdriver#quickstart\n[TraceExporterZipkin]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/trace/zipkin#quickstart\n[StatsExporterStackdriver]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/stackdriver#quickstart\n[StatsExporterSignalFx]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/signalfx#quickstart\n[StatsExporterPrometheus]: https://github.com/census-instrumentation/opencensus-java/tree/master/exporters/stats/prometheus#quickstart\n","funding_links":[],"categories":["Java (78)","Integrations","Google Cloud Trace"],"sub_categories":["Java","Client libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcensus-instrumentation%2Fopencensus-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcensus-instrumentation%2Fopencensus-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcensus-instrumentation%2Fopencensus-java/lists"}