Google Cloud Trace SDK for Java is a Java library that provides tools, best practices, and examples for integrating with Google Cloud Trace, a feature of Google Cloud Platform that collects, displays, and analyzes latency data from applications.
NOTE: Google Cloud Trace SDK for Java currently depends on the Google Trace API, which is currently only available to selected Google Cloud users. The API should be widely available within the next few weeks.
- Note the current list of open issues in the Github issue tracker.
- Clone this repository.
- See the CONTRIBUTING file in the root directory.
- The project is organized into a "core" module that contains the main library classes and interfaces, and optional submodules for platform-specific additions (servlets, etc.).
- There is a top-level Maven pom that builds them all:
mvn install- Make sure to add and run tests as appropriate before submitting patch requests.
Releases will be tagged in the repository and an announcement will be made on our Github page. We have no strict timetable but aim to do this every three months or whenever a more urgent need arises.
- gRPC Integration
- Guice/Spring submodules (e.g. injecting TraceContext into request scopes).
- HttpClient integration (including trace header forwarding on outgoing requests).
- Clone the project and build from source (see above).
- Maven dependency for the core module:
<dependency>
<groupId>com.google.cloud.trace</groupId>
<artifactId>google-cloud-trace-sdk-core</artifactId>
<version>0.1-SNAPSHOT</version>
</dependency>
TraceSpanData contains the key data for a specific timing, including start and end times, name, and parent span (if any). It can also hold arbitrary user-defined key-value data. The key focus of the SDK is on the creation and management of TraceSpanData instances.
TraceContext associates a span with a specific trace. It should be propagated across the wire (for example, serialized in a well-defined HTTP header -- see TraceHeader.java) to support cross-node and cross-application tracing.
This interface exposes the data needed to construct a TraceSpanData. To create a TraceSpanData, you will first create an instance of a TraceSpanBuilder implementation, then pass that instance to the TraceSpanData constructor. There is a default implementation, DefaultTraceSpanDataBuilder, that creates a TraceSpanData from simple values.
TraceWriter is an interface that serves as a sink for completed TraceSpanData instances, writing them directly to the Cloud Trace API, or to a log for later processing (for example).
This is a convenience class that wraps a TraceSpanData in a Java AutoClosable implementation that will automatically end a span and write it out via a TraceWriter.
The core SDK includes a couple of TraceWriter implementations that write out data, along with some decorators that implement specific writing policies.
LoggingTraceWriter writes TraceSpanData instances out to a standard Java log file at the INFO level. These may later be forwarded to the Cloud Trace API out-of-band using a separate application or logs processor like FluentD.
CloudTraceWriter contains all of the logic needed to call the Cloud Trace API (JSON in an HTTP PATCH request). Because TraceWriter is span-oriented and the API is trace-oriented, for efficiency purposes it contains the logic to aggregate spans by trace before forwarding them along.
This is a decorator TraceWriter implementation that batches a number of trace span data instances prior to delegating them to the underlying TraceWriter.
The Cloud Trace API requires OAuth2 credentials to be provided on each call. (See the Cloud Trace API documentation for more details.) To ease this process, the Cloud Trace SDK has an interface, CredentialProvider, with the following implementations, all of which can be configured in a .properties file:
- InstalledAppCredentialProvider
- LocalMetadataCredentialProvider
- ServiceAccountCredentialProvider
An interface, TraceEnablingPolicy, is provided to allow TraceSpanDataBuilder's a structured way, when creating new TraceContext's, to request writers to write or not write traces. Built-in implementations include:
- Always/NeverTraceEnablingPolicy
- PercentageTraceEnablingPolicy -- allows a configurable percentage of traces to be written.
- RateLimiterTraceEnablingPolicy -- allows rate-limited traces.
- ForwardingTraceEnablingPolicy -- forwards the incoming write/don't state.
Submodules are separate libraries that depend on the core Cloud Trace SDK and add additional functionality to integrate with specific libraries, frameworks, and platforms.
The main contribution of the Servlet submodule is a servlet Filter, TraceFilter, that when installed will automatically manage a new TraceSpanData instance (including processing any incoming trace header) and install it on the servlet Request context. Install and configure in web.xml.
<dependency>
<groupId>com.google.cloud.trace</groupId>
<artifactId>google-cloud-trace-sdk-servlet</artifactId>
<version>0.1-SNAPSHOT</version>
</dependency>
For Google App Engine, we trace requests and their outgoing API calls automatically. You can view Google App Engine traces in Google Developers Console.
Users can add additional spans to Google App Egnine traces by using this SDK. We provide a sample app hello-trace that shows how to add custom spans to Google App Engine traces.
<dependency>
<groupId>com.google.cloud.trace</groupId>
<artifactId>google-cloud-trace-sdk-gae</artifactId>
<version>0.1-SNAPSHOT</version>
</dependency>