open-telemetry
/
opentelemetry-java
mirror of https://github.com/open-telemetry/opentelemetry-java.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update the quickstart for 0.13.1 (#2362)

This commit is contained in:
John Watson 2020-12-18 13:19:29 -08:00 committed by GitHub
parent fb5b497986
commit 9f01907e19
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 75 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
QUICKSTART.md
View File

@ -3,7 +3,7 @@
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` --> <!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc --> <!-- toc -->
- [Set up](#set-up)
- [Tracing](#tracing) - [Tracing](#tracing)
* [Create basic Span](#create-basic-span) * [Create basic Span](#create-basic-span)
* [Create nested Spans](#create-nested-spans) * [Create nested Spans](#create-nested-spans)
@ -31,6 +31,34 @@ configuration must be provided by **Applications** which should also depend on t
libraries will obtain a real implementation only if the user application is configured for it. For libraries will obtain a real implementation only if the user application is configured for it. For
more details, check out the [Library Guidelines]. more details, check out the [Library Guidelines].
## Set up
The first step is to get a handle to an instance of the `OpenTelemetry` interface.
If you are an application developer, you need to configure an instance of the `OpenTelemetrySdk` as
early as possible in your application. This can be done using the `OpenTelemetrySdk.builder()` method.
For example:
```java
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
sdkTracerProvider.addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder().build()).build());
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
.setTracerProvider(sdkTracerProvider)
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.build();
//optionally set this instance as the global instance:
GlobalOpenTelemetry.set(openTelemetry);
```
As an aside, if you are writing library instrumentation, it is strongly recommended that you provide your users
the ability to inject an instance of `OpenTelemetry` into your instrumentation code. If this is
not possible for some reason, you can fall back to using an instance from the `GlobalOpenTelemetry`
class. Note that you can't force end-users to configure the global, so this is the most brittle
option for library instrumentation.
## Tracing ## Tracing
In the following, we present how to trace code using the OpenTelemetry API. **Note:** Methods of the In the following, we present how to trace code using the OpenTelemetry API. **Note:** Methods of the
@ -43,14 +71,18 @@ monitored. More information is available in the specification chapter [Obtaining
```java ```java
Tracer tracer = Tracer tracer =
OpenTelemetry.getGlobalTracer("instrumentation-library-name", "1.0.0"); openTelemetry.getTracer("instrumentation-library-name", "1.0.0");
``` ```
Important: the "name" and optional version of the tracer are purely informational.
All `Tracer`s that are created by a single `OpenTelemetry` instance will interoperate, regardless of name.
### Create basic Span ### Create basic Span
To create a basic span, you only need to specify the name of the span. To create a basic span, you only need to specify the name of the span.
The start and end time of the span is automatically set by the OpenTelemetry SDK. The start and end time of the span is automatically set by the OpenTelemetry SDK.
```java ```java
Span span = tracer.spanBuilder("my span").startSpan(); Span span = tracer.spanBuilder("my span").startSpan();
// put the span into the current Context
try (Scope scope = span.makeCurrent()) { try (Scope scope = span.makeCurrent()) {
// your use case // your use case
... ...
@ -195,7 +227,7 @@ try (Scope scope = outGoing.makeCurrent()) {
outGoing.setAttribute(SemanticAttributes.HTTP_URL, url.toString()); outGoing.setAttribute(SemanticAttributes.HTTP_URL, url.toString());
HttpURLConnection transportLayer = (HttpURLConnection) url.openConnection(); HttpURLConnection transportLayer = (HttpURLConnection) url.openConnection();
// Inject the request with the *current* Context, which contains our current Span. // Inject the request with the *current* Context, which contains our current Span.
OpenTelemetry.getGlobalPropagators().getTextMapPropagator().inject(Context.current(), transportLayer, setter); openTelemetry.getPropagators().getTextMapPropagator().inject(Context.current(), transportLayer, setter);
// Make outgoing call // Make outgoing call
} finally { } finally {
outGoing.end(); outGoing.end();
@ -226,7 +258,7 @@ TextMapPropagator.Getter<HttpExchange> getter =
... ...
public void handle(HttpExchange httpExchange) { public void handle(HttpExchange httpExchange) {
// Extract the SpanContext and other elements from the request. // Extract the SpanContext and other elements from the request.
Context extractedContext = OpenTelemetry.getGlobalPropagators().getTextMapPropagator() Context extractedContext = openTelemetry.getPropagators().getTextMapPropagator()
.extract(Context.current(), httpExchange, getter); .extract(Context.current(), httpExchange, getter);
try (Scope scope = extractedContext.makeCurrent()) { try (Scope scope = extractedContext.makeCurrent()) {
// Automatically use the extracted SpanContext as parent. // Automatically use the extracted SpanContext as parent.
@ -248,21 +280,28 @@ public void handle(HttpExchange httpExchange) {
} }
``` ```
## Metrics ## Metrics (alpha only!)
Spans are a great way to get detailed information about what your application is doing, but Spans are a great way to get detailed information about what your application is doing, but
what about a more aggregated perspective? OpenTelemetry provides supports for metrics, a time series what about a more aggregated perspective? OpenTelemetry provides supports for metrics, a time series
of numbers that might express things such as CPU utilization, request count for an HTTP server, or a of numbers that might express things such as CPU utilization, request count for an HTTP server, or a
business metric such as transactions. business metric such as transactions.
In order to access the alpha metrics library, you will need to explicitly depend on the `opentelemetry-api-metrics`
and `opentelemetry-sdk-metrics` modules, which are not included in the opentelemetry-bom until they are
stable and ready for long-term-support.
All metrics can be annotated with labels: additional qualifiers that help describe what All metrics can be annotated with labels: additional qualifiers that help describe what
subdivision of the measurements the metric represents. subdivision of the measurements the metric represents.
First, you'll need to get access to a `MeterProvider`. Note the APIs for this are in flux, so no
example code is provided here for that.
The following is an example of counter usage: The following is an example of counter usage:
```java ```java
// Gets or creates a named meter instance // Gets or creates a named meter instance
Meter meter = OpenTelemetry.getGlobalMeter("instrumentation-library-name", "1.0.0"); Meter meter = meterProvider.getMeter("instrumentation-library-name", "1.0.0");
// Build counter e.g. LongCounter // Build counter e.g. LongCounter
LongCounter counter = meter LongCounter counter = meter
@ -315,18 +354,12 @@ mechanisms.
The application has to install a span processor with an exporter and may customize the behavior of The application has to install a span processor with an exporter and may customize the behavior of
the OpenTelemetry SDK. the OpenTelemetry SDK.
For example, a basic configuration instantiates the SDK tracer registry and sets to export the For example, a basic configuration instantiates the SDK tracer provider and sets to export the
traces to a logging stream. traces to a logging stream.
```java ```java
// Get the tracer management interface SdkTracerProvider tracerProvider = SdkTracerProvider.builder().build();
TracerSdkManagement tracerSdkManagement = OpenTelemetrySdk.getGlobalTracerManagement(); tracerProvider.addSpanProcessor(BatchSpanProcessor.builder(new LoggingSpanExporter()).build());
// Set to export the traces to a logging stream
tracerSdkManagement.addSpanProcessor(
SimpleSpanProcessor.builder(
new LoggingSpanExporter()
).build());
``` ```
### Sampler ### Sampler
@ -368,16 +401,13 @@ in bulk. Multiple Span processors can be configured to be active at the same tim
`MultiSpanProcessor`. `MultiSpanProcessor`.
```java ```java
tracerSdkManagement.addSpanProcessor( SdkTracerProvider tracerProvider = SdkTracerProvider.builder().build();
SimpleSpanProcessor.builder(new LoggingSpanExporter()).build() tracerProvider.addSpanProcessor(
); MultiSpanProcessor.create(Arrays.asList(
tracerSdkManagement.addSpanProcessor( SimpleSpanProcessor.builder(new LoggingSpanExporter()).build(),
BatchSpanProcessor.builder(new LoggingSpanExporter()).build() BatchSpanProcessor.builder(new LoggingSpanExporter()).build()
); ))
tracerSdkManagement.addSpanProcessor(MultiSpanProcessor.create(Arrays.asList( );
SimpleSpanProcessor.builder(new LoggingSpanExporter()).build(),
BatchSpanProcessor.builder(new LoggingSpanExporter()).build()
)));
``` ```
### Exporter ### Exporter
@ -393,19 +423,14 @@ a particular backend. OpenTelemetry offers five exporters out of the box:
Other exporters can be found in the [OpenTelemetry Registry]. Other exporters can be found in the [OpenTelemetry Registry].
```java ```java
tracerSdkManagement.addSpanProcessor(
SimpleSpanProcessor.builder(InMemorySpanExporter.create()).build());
tracerSdkManagement.addSpanProcessor(
SimpleSpanProcessor.builder(new LoggingSpanExporter()).build());
ManagedChannel jaegerChannel = ManagedChannel jaegerChannel =
ManagedChannelBuilder.forAddress([ip:String], [port:int]).usePlaintext().build(); ManagedChannelBuilder.forAddress([ip:String], [port:int]).usePlaintext().build();
JaegerGrpcSpanExporter jaegerExporter = JaegerGrpcSpanExporter.builder() JaegerGrpcSpanExporter jaegerExporter = JaegerGrpcSpanExporter.builder()
.setServiceName("example").setChannel(jaegerChannel).setDeadline(30000) .setServiceName("example").setChannel(jaegerChannel).setDeadline(30000)
.build(); .build()
tracerSdkManagement.addSpanProcessor(BatchSpanProcessor.builder(
jaegerExporter SdkTracerProvider tracerProvider = SdkTracerProvider.builder().build();
).build()); tracerProvider.addSpanProcessor(BatchSpanProcessor.builder(jaegerExporter).build()));
``` ```
### TraceConfig ### TraceConfig
@ -414,23 +439,20 @@ The `TraceConfig` associated with a Tracer SDK can be updated via system propert
environment variables and builder `set*` methods. environment variables and builder `set*` methods.
```java ```java
// Get TraceConfig associated with TracerSdk // Get TraceConfig Builder
TracerConfig traceConfig = OpenTelemetrySdk.getGlobalTracerManagement().getActiveTraceConfig(); TraceConfigBuilder builder = TraceConfig.builder();
// Get TraceConfig Builder // Read configuration options from system properties
Builder builder = traceConfig.toBuilder(); builder.readSystemProperties();
// Read configuration options from system properties // Read configuration options from environment variables
builder.readSystemProperties(); builder.readEnvironmentVariables()
// Read configuration options from environment variables // Set options via builder.set* methods, e.g.
builder.readEnvironmentVariables() builder.setMaxNumberOfLinks(10);
// Set options via builder.set* methods, e.g. // Use the resulting TraceConfig instance
builder.setMaxNumberOfLinks(10); SdkTracerProvider tracerProvider = SdkTracerProvider.builder().setTraceConfig(traceConfig).build();
// Update the resulting TraceConfig instance
OpenTelemetrySdk.getGlobalTracerManagement().updateActiveTraceConfig(builder.build());
``` ```
Supported system properties and environment variables: Supported system properties and environment variables: