Skip to content

Commit 41a298c

Browse files
jkwatsonjkwatson
authored
update the QUICKSTART.md for 0.14.1 (open-telemetry#2539)
1 parent 8e0d7fb commit 41a298c

1 file changed

Lines changed: 35 additions & 50 deletions

File tree

‎QUICKSTART.md‎

Lines changed: 35 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ out the [OpenTelemetry Website].
2929
configuration must be provided by **Applications** which should also depend on the
3030
`opentelemetry-sdk` package, or any other implementation of the OpenTelemetry API. This way,
3131
libraries will obtain a real implementation only if the user application is configured for it. For
32-
more details, check out the [Library Guidelines].
32+
more details, check out the [Library Guidelines].
3333

3434
## Set up
3535

@@ -38,19 +38,21 @@ The first step is to get a handle to an instance of the `OpenTelemetry` interfac
3838
If you are an application developer, you need to configure an instance of the `OpenTelemetrySdk` as
3939
early as possible in your application. This can be done using the `OpenTelemetrySdk.builder()` method.
4040

41+
If you want to enable auto-configuration, via the standard set of environment variables, system
42+
properties or pre-build java SPI implementations, you will want to additionally have your project
43+
depend on the `opentelemetry-sdk-extension-autoconfigure` module.
44+
4145
For example:
4246

4347
```java
44-
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder().build();
45-
sdkTracerProvider.addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder().build()).build());
46-
48+
SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
49+
.addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder().build()))
50+
.build();
51+
4752
OpenTelemetry openTelemetry = OpenTelemetrySdk.builder()
48-
.setTracerProvider(sdkTracerProvider)
49-
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
50-
.build();
51-
52-
//optionally set this instance as the global instance:
53-
GlobalOpenTelemetry.set(openTelemetry);
53+
.setTracerProvider(sdkTracerProvider)
54+
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
55+
.buildAndRegisterGlobal();
5456
```
5557

5658
As an aside, if you are writing library instrumentation, it is strongly recommended that you provide your users
@@ -358,8 +360,9 @@ For example, a basic configuration instantiates the SDK tracer provider and sets
358360
traces to a logging stream.
359361

360362
```java
361-
SdkTracerProvider tracerProvider = SdkTracerProvider.builder().build();
362-
tracerProvider.addSpanProcessor(BatchSpanProcessor.builder(new LoggingSpanExporter()).build());
363+
SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
364+
.addSpanProcessor(BatchSpanProcessor.builder(new LoggingSpanExporter()).build())
365+
.build();
363366
```
364367

365368
### Sampler
@@ -378,19 +381,14 @@ Additional samplers can be provided by implementing the `io.opentelemetry.sdk.tr
378381
interface.
379382

380383
```java
381-
TraceConfig alwaysOn = TraceConfig.getDefault().toBuilder().setSampler(
382-
Sampler.alwaysOn()
383-
).build();
384-
TraceConfig alwaysOff = TraceConfig.getDefault().toBuilder().setSampler(
385-
Sampler.alwaysOff()
386-
).build();
387-
TraceConfig half = TraceConfig.getDefault().toBuilder().setSampler(
388-
Sampler.traceIdRatioBased(0.5)
389-
).build();
390-
// Configure the sampler to use
391-
tracerProvider.updateActiveTraceConfig(
392-
half
393-
);
384+
TraceConfig alwaysOn = TraceConfig.getDefault().toBuilder().setSampler(Sampler.alwaysOn()).build();
385+
TraceConfig alwaysOff = TraceConfig.getDefault().toBuilder().setSampler(Sampler.alwaysOff()).build();
386+
TraceConfig half = TraceConfig.getDefault().toBuilder().setSampler(Sampler.traceIdRatioBased(0.5)).build();
387+
388+
// You configure the sampler when building the SDK implementation:
389+
SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
390+
.setTraceConfig(half)
391+
.build();
394392
```
395393

396394
### Span Processor
@@ -401,13 +399,13 @@ in bulk. Multiple Span processors can be configured to be active at the same tim
401399
`MultiSpanProcessor`.
402400

403401
```java
404-
SdkTracerProvider tracerProvider = SdkTracerProvider.builder().build();
405-
tracerProvider.addSpanProcessor(
406-
MultiSpanProcessor.create(Arrays.asList(
407-
SimpleSpanProcessor.builder(new LoggingSpanExporter()).build(),
408-
BatchSpanProcessor.builder(new LoggingSpanExporter()).build()
409-
))
410-
);
402+
SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
403+
.addSpanProcessor(
404+
MultiSpanProcessor.create(Arrays.asList(
405+
SimpleSpanProcessor.create(new LoggingSpanExporter()),
406+
BatchSpanProcessor.builder(new LoggingSpanExporter()).build()
407+
)))
408+
.build();
411409
```
412410

413411
### Exporter
@@ -433,29 +431,16 @@ ManagedChannel jaegerChannel =
433431
tracerProvider.addSpanProcessor(BatchSpanProcessor.builder(jaegerExporter).build()));
434432
```
435433

436-
### TraceConfig
434+
### Auto Configuration
437435

438-
The `TraceConfig` associated with a Tracer SDK can be updated via system properties,
439-
environment variables and builder `set*` methods.
436+
To configure the OpenTelemetry SDK based on the standard set of environment variables and system
437+
properties, you can use the `opentelemetry-sdk-extension-autoconfigure` module.
440438

441439
```java
442-
// Get TraceConfig Builder
443-
TraceConfigBuilder builder = TraceConfig.builder();
444-
445-
// Read configuration options from system properties
446-
builder.readSystemProperties();
447-
448-
// Read configuration options from environment variables
449-
builder.readEnvironmentVariables()
450-
451-
// Set options via builder.set* methods, e.g.
452-
builder.setMaxNumberOfLinks(10);
453-
454-
// Use the resulting TraceConfig instance
455-
SdkTracerProvider tracerProvider = SdkTracerProvider.builder().setTraceConfig(traceConfig).build();
440+
OpenTelemetrySdk sdk = OpenTelemetrySdkAutoConfiguration.initialize();
456441
```
457442

458-
Supported system properties and environment variables:
443+
Some of the supported system properties and environment variables:
459444

460445
| System property | Environment variable | Purpose |
461446
|----------------------------------|----------------------------------|-----------------------------------------------------------------------------------------------------|

0 commit comments

Comments
 (0)