Skip to content

Commit dd12ee9

Browse files
jack-bergjack-berg
authored
Add api usage snippets (#498)
1 parent f7f3883 commit dd12ee9

23 files changed

+1129
-0
lines changed

‎doc-snippets/api/build.gradle.kts

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
plugins {
2+
id("java")
3+
}
4+
5+
val moduleName by extra { "io.opentelemetry.examples.docs.configuration" }
6+
7+
dependencies {
8+
implementation("io.opentelemetry:opentelemetry-api")
9+
10+
implementation("io.opentelemetry.semconv:opentelemetry-semconv")
11+
implementation("io.opentelemetry.semconv:opentelemetry-semconv-incubating:1.26.0-alpha")
12+
}

‎doc-snippets/api/src/main/java/otel/AsyncCounterUsage.java

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
package otel;
2+
3+
import static otel.Util.WIDGET_COLOR;
4+
import static otel.Util.WIDGET_SHAPE;
5+
import static otel.Util.computeWidgetColor;
6+
import static otel.Util.computeWidgetShape;
7+
8+
import io.opentelemetry.api.common.Attributes;
9+
import io.opentelemetry.api.metrics.Meter;
10+
import io.opentelemetry.api.metrics.ObservableLongCounter;
11+
import java.util.concurrent.atomic.AtomicLong;
12+
13+
public class AsyncCounterUsage {
14+
// Pre-allocate attributes whenever possible
15+
private static final Attributes WIDGET_RED_CIRCLE = Util.WIDGET_RED_CIRCLE;
16+
17+
public static void asyncCounterUsage(Meter meter) {
18+
AtomicLong widgetCount = new AtomicLong();
19+
20+
// Construct an async counter to observe an existing counter in a callback
21+
ObservableLongCounter asyncCounter =
22+
meter
23+
.counterBuilder("fully.qualified.counter")
24+
.setDescription("A count of produced widgets")
25+
.setUnit("{widget}")
26+
// Uncomment to optionally change the type to double
27+
// .ofDoubles()
28+
.buildWithCallback(
29+
// the callback is invoked a MetricReader reads metrics
30+
observableMeasurement -> {
31+
long currentWidgetCount = widgetCount.get();
32+
33+
// Record a measurement with no attributes.
34+
// Attributes defaults to Attributes.empty().
35+
observableMeasurement.record(currentWidgetCount);
36+
37+
// Record a measurement with attributes, using pre-allocated attributes whenever
38+
// possible.
39+
observableMeasurement.record(currentWidgetCount, WIDGET_RED_CIRCLE);
40+
// Sometimes, attributes must be computed using application context.
41+
observableMeasurement.record(
42+
currentWidgetCount,
43+
Attributes.of(
44+
WIDGET_SHAPE, computeWidgetShape(), WIDGET_COLOR, computeWidgetColor()));
45+
});
46+
47+
// Optionally close the counter to unregister the callback when required
48+
asyncCounter.close();
49+
}
50+
}

‎doc-snippets/api/src/main/java/otel/AsyncGaugeUsage.java

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
package otel;
2+
3+
import static otel.Util.WIDGET_COLOR;
4+
import static otel.Util.WIDGET_SHAPE;
5+
import static otel.Util.computeWidgetColor;
6+
import static otel.Util.computeWidgetShape;
7+
8+
import io.opentelemetry.api.common.Attributes;
9+
import io.opentelemetry.api.metrics.Meter;
10+
import io.opentelemetry.api.metrics.ObservableDoubleGauge;
11+
import java.util.concurrent.atomic.AtomicReference;
12+
13+
public class AsyncGaugeUsage {
14+
private static final Attributes WIDGET_RED_CIRCLE = Util.WIDGET_RED_CIRCLE;
15+
16+
public static void asyncGaugeUsage(Meter meter) {
17+
AtomicReference<Double> processingLineTemp = new AtomicReference<>(273.0);
18+
19+
// Construct an async counter to observe an existing counter in a callback
20+
ObservableDoubleGauge asyncGauge =
21+
meter
22+
.gaugeBuilder("fully.qualified.gauge")
23+
.setDescription("The current temperature of the widget processing line")
24+
.setUnit("K")
25+
// Uncomment to optionally change the type to long
26+
// .ofLongs()
27+
.buildWithCallback(
28+
// the callback is invoked a MetricReader reads metrics
29+
observableMeasurement -> {
30+
double currentWidgetCount = processingLineTemp.get();
31+
32+
// Record a measurement with no attributes.
33+
// Attributes defaults to Attributes.empty().
34+
observableMeasurement.record(currentWidgetCount);
35+
36+
// Record a measurement with attributes, using pre-allocated attributes whenever
37+
// possible.
38+
observableMeasurement.record(currentWidgetCount, WIDGET_RED_CIRCLE);
39+
// Sometimes, attributes must be computed using application context.
40+
observableMeasurement.record(
41+
currentWidgetCount,
42+
Attributes.of(
43+
WIDGET_SHAPE, computeWidgetShape(), WIDGET_COLOR, computeWidgetColor()));
44+
});
45+
46+
// Optionally close the gauge to unregister the callback when required
47+
asyncGauge.close();
48+
}
49+
}

‎doc-snippets/api/src/main/java/otel/AsyncUpDownCounterUsage.java

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
package otel;
2+
3+
import static otel.Util.WIDGET_COLOR;
4+
import static otel.Util.WIDGET_SHAPE;
5+
import static otel.Util.computeWidgetColor;
6+
import static otel.Util.computeWidgetShape;
7+
8+
import io.opentelemetry.api.common.Attributes;
9+
import io.opentelemetry.api.metrics.Meter;
10+
import io.opentelemetry.api.metrics.ObservableLongUpDownCounter;
11+
import java.util.concurrent.atomic.AtomicLong;
12+
13+
public class AsyncUpDownCounterUsage {
14+
private static final Attributes WIDGET_RED_CIRCLE = Util.WIDGET_RED_CIRCLE;
15+
16+
public static void asyncUpDownCounterUsage(Meter meter) {
17+
AtomicLong queueLength = new AtomicLong();
18+
19+
// Construct an async updowncounter to observe an existing up down counter in a callback
20+
ObservableLongUpDownCounter asyncUpDownCounter =
21+
meter
22+
.upDownCounterBuilder("fully.qualified.updowncounter")
23+
.setDescription("Current length of widget processing queue")
24+
.setUnit("{widget}")
25+
// Uncomment to optionally change the type to double
26+
// .ofDoubles()
27+
.buildWithCallback(
28+
// the callback is invoked a MetricReader reads metrics
29+
observableMeasurement -> {
30+
long currentWidgetCount = queueLength.get();
31+
32+
// Record a measurement with no attributes.
33+
// Attributes defaults to Attributes.empty().
34+
observableMeasurement.record(currentWidgetCount);
35+
36+
// Record a measurement with attributes, using pre-allocated attributes whenever
37+
// possible.
38+
observableMeasurement.record(currentWidgetCount, WIDGET_RED_CIRCLE);
39+
// Sometimes, attributes must be computed using application context.
40+
observableMeasurement.record(
41+
currentWidgetCount,
42+
Attributes.of(
43+
WIDGET_SHAPE, computeWidgetShape(), WIDGET_COLOR, computeWidgetColor()));
44+
});
45+
46+
// Optionally close the counter to unregister the callback when required
47+
asyncUpDownCounter.close();
48+
}
49+
}

‎doc-snippets/api/src/main/java/otel/AttributesUsage.java

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
package otel;
2+
3+
import io.opentelemetry.api.common.AttributeKey;
4+
import io.opentelemetry.api.common.Attributes;
5+
import io.opentelemetry.api.common.AttributesBuilder;
6+
import java.util.Map;
7+
8+
public class AttributesUsage {
9+
// Establish static constant for attribute keys and reuse to avoid allocations
10+
private static final AttributeKey<String> SHOP_ID = AttributeKey.stringKey("com.acme.shop.id");
11+
private static final AttributeKey<String> SHOP_NAME =
12+
AttributeKey.stringKey("com.acme.shop.name");
13+
private static final AttributeKey<Long> CUSTOMER_ID =
14+
AttributeKey.longKey("com.acme.customer.id");
15+
private static final AttributeKey<String> CUSTOMER_NAME =
16+
AttributeKey.stringKey("com.acme.customer.name");
17+
18+
public static void attributesUsage() {
19+
// Use a varargs initializer and pre-allocated attribute keys. This is the most efficient way to
20+
// create attributes.
21+
Attributes attributes =
22+
Attributes.of(
23+
SHOP_ID,
24+
"abc123",
25+
SHOP_NAME,
26+
"opentelemetry-demo",
27+
CUSTOMER_ID,
28+
123L,
29+
CUSTOMER_NAME,
30+
"Jack");
31+
32+
// ...or use a builder.
33+
attributes =
34+
Attributes.builder()
35+
.put(SHOP_ID, "abc123")
36+
.put(SHOP_NAME, "opentelemetry-demo")
37+
.put(CUSTOMER_ID, 123)
38+
.put(CUSTOMER_NAME, "Jack")
39+
// Optionally initialize attribute keys on the fly
40+
.put(AttributeKey.stringKey("com.acme.string-key"), "value")
41+
.put(AttributeKey.booleanKey("com.acme.bool-key"), true)
42+
.put(AttributeKey.longKey("com.acme.long-key"), 1L)
43+
.put(AttributeKey.doubleKey("com.acme.double-key"), 1.1)
44+
.put(AttributeKey.stringArrayKey("com.acme.string-array-key"), "value1", "value2")
45+
.put(AttributeKey.booleanArrayKey("come.acme.bool-array-key"), true, false)
46+
.put(AttributeKey.longArrayKey("come.acme.long-array-key"), 1L, 2L)
47+
.put(AttributeKey.doubleArrayKey("come.acme.double-array-key"), 1.1, 2.2)
48+
// Optionally omit initializing AttributeKey
49+
.put("com.acme.string-key", "value")
50+
.put("com.acme.bool-key", true)
51+
.put("come.acme.long-key", 1L)
52+
.put("come.acme.double-key", 1.1)
53+
.put("come.acme.string-array-key", "value1", "value2")
54+
.put("come.acme.bool-array-key", true, false)
55+
.put("come.acme.long-array-key", 1L, 2L)
56+
.put("come.acme.double-array-key", 1.1, 2.2)
57+
.build();
58+
59+
// Attributes has a variety of methods for manipulating and reading data.
60+
// Read an attribute key:
61+
String shopIdValue = attributes.get(SHOP_ID);
62+
// Inspect size:
63+
int size = attributes.size();
64+
boolean isEmpty = attributes.isEmpty();
65+
// Convert to a map representation:
66+
Map<AttributeKey<?>, Object> map = attributes.asMap();
67+
// Iterate through entries, printing each to the template: <key> (<type>): <value>\n
68+
attributes.forEach(
69+
(attributeKey, value) ->
70+
System.out.printf(
71+
"%s (%s): %s%n", attributeKey.getKey(), attributeKey.getType(), value));
72+
// Convert to a builder, remove the com.acme.customer.id and any entry whose key starts with
73+
// com.acme.shop, and build a new instance:
74+
AttributesBuilder builder = attributes.toBuilder();
75+
builder.remove(CUSTOMER_ID);
76+
builder.removeIf(attributeKey -> attributeKey.getKey().startsWith("com.acme.shop"));
77+
Attributes trimmedAttributes = builder.build();
78+
}
79+
}

‎doc-snippets/api/src/main/java/otel/BaggageUsage.java

+74
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
package otel;
2+
3+
import static io.opentelemetry.context.Context.current;
4+
5+
import io.opentelemetry.api.baggage.Baggage;
6+
import io.opentelemetry.api.baggage.BaggageEntry;
7+
import io.opentelemetry.api.baggage.BaggageEntryMetadata;
8+
import io.opentelemetry.api.common.Attributes;
9+
import io.opentelemetry.context.Scope;
10+
import java.util.Map;
11+
import java.util.stream.Collectors;
12+
13+
public class BaggageUsage {
14+
private static final Attributes WIDGET_RED_CIRCLE = Util.WIDGET_RED_CIRCLE;
15+
16+
public static void baggageUsage() {
17+
// Access current baggage with Baggage.current()
18+
// output => context baggage: {}
19+
Baggage currentBaggage = Baggage.current();
20+
System.out.println("current baggage: " + asString(currentBaggage));
21+
// ...or from a Context
22+
currentBaggage = Baggage.fromContext(current());
23+
24+
// Baggage has a variety of methods for manipulating and reading data.
25+
// Convert to builder and add entries:
26+
Baggage newBaggage =
27+
Baggage.current().toBuilder()
28+
.put("shopId", "abc123")
29+
.put("shopName", "opentelemetry-demo", BaggageEntryMetadata.create("metadata"))
30+
.build();
31+
// ...or uncomment to start from empty
32+
// newBaggage = Baggage.empty().toBuilder().put("shopId", "abc123").build();
33+
// output => new baggage: {shopId=abc123(), shopName=opentelemetry-demo(metadata)}
34+
System.out.println("new baggage: " + asString(newBaggage));
35+
// Read an entry:
36+
String shopIdValue = newBaggage.getEntryValue("shopId");
37+
// Inspect size:
38+
int size = newBaggage.size();
39+
boolean isEmpty = newBaggage.isEmpty();
40+
// Convert to map representation:
41+
Map<String, BaggageEntry> map = newBaggage.asMap();
42+
// Iterate through entries:
43+
newBaggage.forEach((s, baggageEntry) -> {});
44+
45+
// The current baggage still doesn't contain the new entries
46+
// output => context baggage: {}
47+
System.out.println("current baggage: " + asString(Baggage.current()));
48+
49+
// Calling Baggage.makeCurrent() sets Baggage.current() to the baggage until the scope is
50+
// closed, upon which Baggage.current() is restored to the state prior to when
51+
// Baggage.makeCurrent() was called.
52+
try (Scope scope = newBaggage.makeCurrent()) {
53+
// The current baggage now contains the added value
54+
// output => context baggage: {shopId=abc123(), shopName=opentelemetry-demo(metadata)}
55+
System.out.println("current baggage: " + asString(Baggage.current()));
56+
}
57+
58+
// The current baggage no longer contains the new entries:
59+
// output => context baggage: {}
60+
System.out.println("current baggage: " + asString(Baggage.current()));
61+
}
62+
63+
private static String asString(Baggage baggage) {
64+
return baggage.asMap().entrySet().stream()
65+
.map(
66+
entry ->
67+
String.format(
68+
"%s=%s(%s)",
69+
entry.getKey(),
70+
entry.getValue().getValue(),
71+
entry.getValue().getMetadata().getValue()))
72+
.collect(Collectors.joining(", ", "{", "}"));
73+
}
74+
}

0 commit comments

Comments
 (0)