Bug: 117828010

Clone this repo:
  1. c381ccc Specify min_sdk_version so it can be used with APEX. by Alex Buynytskyy · 7 weeks ago main-16k-with-phones master
  2. d1b7045 Remove log4j and its references from opencensus am: 8fd12cb94e am: 1109620313 am: 1a0247bd40 am: ef47135fc4 by Guang Zhu · 1 year, 2 months ago android13-dev android13-frc-adbd-release android13-frc-art-release android13-frc-cellbroadcast-release android13-frc-conscrypt-release android13-mainline-adservices-release android13-mainline-appsearch-release android13-mainline-go-adbd-release android13-mainline-go-adservices-release android13-mainline-go-appsearch-release android13-mainline-go-media-swcodec-release android13-mainline-go-mediaprovider-release android13-mainline-go-networking-release android13-mainline-go-neuralnetworks-release android13-mainline-go-odp-release android13-mainline-go-os-statsd-release android13-mainline-go-permission-release android13-mainline-go-resolv-release android13-mainline-go-scheduling-release android13-mainline-go-sdkext-release android13-mainline-go-tethering-release android13-mainline-go-tzdata4-release android13-mainline-go-uwb-release android13-mainline-go-wifi-release android13-mainline-tzdata4-release android13-mainline-uwb-release android13-qpr1-release android13-qpr1-s1-release android13-qpr1-s2-release android13-qpr1-s3-release android13-qpr1-s4-release android13-qpr1-s5-release main-16k aml_ads_331131000 aml_ase_331011020 aml_ase_331112000 aml_go_adb_330913000 aml_go_ads_330913000 aml_go_ase_330913000 aml_go_mpr_330912000 aml_go_net_330913000 aml_go_neu_330912000 aml_go_odp_330912000 aml_go_per_330912000 aml_go_res_330912000 aml_go_sch_330911000 aml_go_sdk_330810000 aml_go_sta_330911000 aml_go_swc_330913000 aml_go_tet_330914010 aml_go_tz4_330912000 aml_go_uwb_330912000 aml_go_wif_330911000 aml_tz4_331012000 aml_tz4_331012040 aml_tz4_331012050 aml_tz4_331314010 aml_uwb_330810010 aml_uwb_331015040 aml_uwb_331115000 aml_uwb_331310030 android-13.0.0_r16 android-13.0.0_r17 android-13.0.0_r18 android-13.0.0_r19 android-13.0.0_r20 android-13.0.0_r21 android-13.0.0_r22 android-13.0.0_r23 android-13.0.0_r24 t_frc_adb_330444000 t_frc_art_330443060 t_frc_ase_330444010 t_frc_cbr_330443000 t_frc_con_330443020 t_frc_odp_330442000
  3. ef47135 Remove log4j and its references from opencensus am: 8fd12cb94e am: 1109620313 am: 1a0247bd40 by Guang Zhu · 1 year, 2 months ago
  4. 1a0247b Remove log4j and its references from opencensus am: 8fd12cb94e am: 1109620313 by Guang Zhu · 1 year, 2 months ago
  5. 1109620 Remove log4j and its references from opencensus am: 8fd12cb94e by Guang Zhu · 1 year, 2 months ago

OpenCensus - A stats collection and distributed tracing framework

Gitter chat Maven Central Javadocs Build Status Windows Build Status Coverage Status

OpenCensus is a toolkit for collecting application performance and behavior data. It currently includes 3 apis: stats, tracing and tags.

The library is in Beta stage and APIs are expected to be mostly stable. The library is expected to move to GA stage after v1.0.0 major release.

Please join gitter for help or feedback on this project.

OpenCensus Quickstart for Libraries

Integrating OpenCensus with a new library means recording stats or traces and propagating context. For application integration please see Quickstart for Applications.

The full quick start example can also be found on the OpenCensus website.

Add the dependencies to your project

For Maven add to your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-api</artifactId>
    <version>0.16.1</version>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

compile 'io.opencensus:opencensus-api:0.16.1'

For Bazel add the following lines to the WORKSPACE file:

maven_jar(
    name = "io_opencensus_opencensus_api",
    artifact = "io.opencensus:opencensus-api:0.15.0",
    sha1 = "9a098392b287d7924660837f4eba0ce252013683",
)

Then targets can specify @io_opencensus_opencensus_api//jar as a dependency to depend on this jar:

deps = [
    "@io_opencensus_opencensus_api//jar",
]

You may also need to import the transitive dependencies. See generate external dependencies from Maven projects.

Hello “OpenCensus” trace events

Here's an example of creating a Span and record some trace annotations. Notice that recording the annotations is possible because we propagate scope. 3rd parties libraries like SLF4J can integrate the same way.

import io.opencensus.common.Scope;
import io.opencensus.trace.Tracer;
import io.opencensus.trace.Tracing;
import io.opencensus.trace.samplers.Samplers;

public final class MyClassWithTracing {
  private static final Tracer tracer = Tracing.getTracer();

  public static void doWork() {
    // Create a child Span of the current Span. Always record events for this span and force it to
    // be sampled. This makes it easier to try out the example, but unless you have a clear use
    // case, you don't need to explicitly set record events or sampler.
    try (Scope ss =
        tracer
            .spanBuilder("MyChildWorkSpan")
            .setRecordEvents(true)
            .setSampler(Samplers.alwaysSample())
            .startScopedSpan()) {
      doInitialWork();
      tracer.getCurrentSpan().addAnnotation("Finished initial work");
      doFinalWork();
    }
  }

  private static void doInitialWork() {
    // ...
    tracer.getCurrentSpan().addAnnotation("Important.");
    // ...
  }

  private static void doFinalWork() {
    // ...
    tracer.getCurrentSpan().addAnnotation("More important.");
    // ...
  }
}

Hello “OpenCensus” stats events

Here's an example on

  • defining TagKey, Measure and View,
  • registering a view,
  • putting TagKey and TagValue into a scoped TagContext,
  • recording stats against current TagContext,
  • getting ViewData.

For the complete example, see here.

import io.opencensus.common.Scope;
import io.opencensus.stats.Aggregation;
import io.opencensus.stats.BucketBoundaries;
import io.opencensus.stats.Measure.MeasureLong;
import io.opencensus.stats.Stats;
import io.opencensus.stats.StatsRecorder;
import io.opencensus.stats.View;
import io.opencensus.stats.ViewData;
import io.opencensus.stats.ViewManager;
import io.opencensus.tags.TagKey;
import io.opencensus.tags.TagValue;
import io.opencensus.tags.Tagger;
import io.opencensus.tags.Tags;
import java.util.Arrays;
import java.util.Collections;

public final class MyClassWithStats {
  private static final Tagger tagger = Tags.getTagger();
  private static final ViewManager viewManager = Stats.getViewManager();
  private static final StatsRecorder statsRecorder = Stats.getStatsRecorder();

  // frontendKey allows us to break down the recorded data
  private static final TagKey FRONTEND_KEY = TagKey.create("myorg_keys_frontend");

  // videoSize will measure the size of processed videos.
  private static final MeasureLong VIDEO_SIZE =
      MeasureLong.create("my.org/measure/video_size", "size of processed videos", "By");

  // Create view to see the processed video size distribution broken down by frontend.
  // The view has bucket boundaries (0, 256, 65536) that will group measure values into
  // histogram buckets.
  private static final View.Name VIDEO_SIZE_VIEW_NAME = View.Name.create("my.org/views/video_size");
  private static final View VIDEO_SIZE_VIEW =
      View.create(
          VIDEO_SIZE_VIEW_NAME,
          "processed video size over time",
          VIDEO_SIZE,
          Aggregation.Distribution.create(
              BucketBoundaries.create(Arrays.asList(0.0, 256.0, 65536.0))),
          Collections.singletonList(FRONTEND_KEY));

  public static void initialize() {
    // ...
    viewManager.registerView(VIDEO_SIZE_VIEW);
  }

  public static void processVideo() {
    try (Scope scopedTags =
        tagger
            .currentBuilder()
            .put(FRONTEND_KEY, TagValue.create("mobile-ios9.3.5"))
            .buildScoped()) {
      // Processing video.
      // ...

      // Record the processed video size.
      statsRecorder.newMeasureMap().put(VIDEO_SIZE, 25648).record();
    }
  }

  public static void printStats() {
    ViewData viewData = viewManager.getView(VIDEO_SIZE_VIEW_NAME);
    System.out.println(
        String.format("Recorded stats for %s:\n %s", VIDEO_SIZE_VIEW_NAME.asString(), viewData));
  }
}

OpenCensus Quickstart for Applications

Besides recording tracing/stats events the application also need to link the implementation, setup exporters, and debugging Z-Pages.

Add the dependencies to your project

For Maven add to your pom.xml:

<dependencies>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-api</artifactId>
    <version>0.16.1</version>
  </dependency>
  <dependency>
    <groupId>io.opencensus</groupId>
    <artifactId>opencensus-impl</artifactId>
    <version>0.16.1</version>
    <scope>runtime</scope>
  </dependency>
</dependencies>

For Gradle add to your dependencies:

compile 'io.opencensus:opencensus-api:0.16.1'
runtime 'io.opencensus:opencensus-impl:0.16.1'

For Bazel add the following lines to the WORKSPACE file:

maven_jar(
    name = "io_opencensus_opencensus_api",
    artifact = "io.opencensus:opencensus-api:0.15.0",
    sha1 = "9a098392b287d7924660837f4eba0ce252013683",
)

maven_jar(
    name = "io_opencensus_opencensus_impl_core",
    artifact = "io.opencensus:opencensus-impl-core:0.15.0",
    sha1 = "36c775926ba1e54af7c37d0503cfb99d986f6229",
)

maven_jar(
    name = "io_opencensus_opencensus_impl",
    artifact = "io.opencensus:opencensus-impl:0.15.0",
    sha1 = "d7bf0d7ee5a0594f840271c11c9f8d6f754f35d6",
)

Then add the following lines to BUILD.bazel file:

deps = [
    "@io_opencensus_opencensus_api//jar",
]
runtime_deps = [
    "@io_opencensus_opencensus_impl_core//jar",
    "@io_opencensus_opencensus_impl//jar",
]

Again you may need to import the transitive dependencies. See generate external dependencies from Maven projects.

How to setup exporters?

Trace exporters

Stats exporters

How to setup debugging Z-Pages?

If the application owner wants to export in-process tracing and stats data via HTML debugging pages see this link.

Versioning

This library follows Semantic Versioning.

GA: Libraries defined at a GA quality level are stable, and will not introduce backwards-incompatible changes in any minor or patch releases. We will address issues and requests with the highest priority. If we were to make a backwards-incompatible changes on an API, we will first mark the existing API as deprecated and keep it for 18 months before removing it.

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we're working towards their release candidate. We will address issues and requests with a higher priority. There may be backwards incompatible changes in a minor version release, though not in a patch release. If an element is part of an API that is only meant to be used by exporters or other opencensus libraries, then there is no deprecation period. Otherwise, we will deprecate it for 18 months before removing it, if possible.