Skip to content

Commit 4e48c0d

Browse files
authored
Merge branch 'main' into build/maven-release-bundles
2 parents 7c73eb5 + 98c60fa commit 4e48c0d

10 files changed

Lines changed: 634 additions & 12 deletions

File tree

‎otel-plugin/README.md‎

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,73 @@ user workers already admitted to their executor, and End does not mean all unawa
7070
late-worker and mandatory large-result acknowledgment boundaries in [#787](https://github.com/aws/aws-durable-execution-sdk-java/issues/787)
7171
remain outside this change.
7272

73+
## Select an OTel view
74+
75+
Import `OtelPlugin` to select the view through one API. Execution mode is the
76+
default; invocation mode is an explicit choice:
77+
78+
```java
79+
import software.amazon.lambda.durable.DurableConfig;
80+
import software.amazon.lambda.durable.otel.OtelPlugin;
81+
82+
// Workflow-rooted operations (default).
83+
var config = DurableConfig.builder().withPlugins(OtelPlugin.factory()).build();
84+
85+
// Invocation-rooted operations.
86+
var invocationConfig = DurableConfig.builder()
87+
.withPlugins(OtelPlugin.factory(OtelPlugin.Mode.INVOCATION))
88+
.build();
89+
```
90+
91+
`OtelPlugin.factory(OtelPlugin.Mode.EXECUTION)` explicitly selects execution mode.
92+
Each call returns a *new* factory of the selected view's type, carrying that
93+
view's configuration and exclusive-group metadata; the SDK then creates a fresh
94+
plugin for each invocation, including concurrent invocations sharing a factory.
95+
96+
Calls are not memoized, so register exactly one. Passing two — for example
97+
`withPlugins(OtelPlugin.factory(), OtelPlugin.factory())` — puts two factories in
98+
the `durable-otel-view` exclusive group and `build()` throws
99+
`IllegalArgumentException`.
100+
101+
Both modes accept the existing `OtelPluginConfig` and application-owned provider
102+
builder. For example:
103+
104+
```java
105+
import io.opentelemetry.sdk.trace.SdkTracerProvider;
106+
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
107+
import software.amazon.lambda.durable.otel.OtelPlugin;
108+
import software.amazon.lambda.durable.otel.OtelPluginConfig;
109+
110+
var settings = OtelPluginConfig.builder().enableMdc(false).build();
111+
var factory = OtelPlugin.factory(OtelPlugin.Mode.INVOCATION,
112+
SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(exporter)),
113+
settings);
114+
```
115+
116+
`OtelPlugin.factory()` is the zero-configuration default. Every overload that
117+
takes configuration or a provider builder names its mode, so the selected view is
118+
explicit wherever it is not the bare default; omit the builder to use the global
119+
provider with the supplied settings. For an execution-view factory with your own
120+
configuration, write `OtelPlugin.factory(OtelPlugin.Mode.EXECUTION, settings)`.
121+
Existing `ExecutionOtelPlugin.factory(...)` and `InvocationOtelPlugin.factory(...)`
122+
calls remain supported.
123+
124+
For loading without handler-side imports or registration, set
125+
`DURABLE_EXECUTION_PLUGINS=otel`. This selects execution mode; `otel-execution`
126+
is still supported and `otel-invocation` selects invocation mode.
127+
128+
**Set exactly one OTel entry name.** `otel` and `otel-execution` select the same
129+
view, but they are separate providers, so listing both puts two factories in the
130+
`durable-otel-view` exclusive group. For example,
131+
`DURABLE_EXECUTION_PLUGINS=otel-execution,otel` fails at startup with:
132+
133+
```text
134+
Conflicting plugin factories otel-execution (ExecutionOtelPlugin) and otel (ExecutionOtelPlugin) in exclusive group 'durable-otel-view'. Configure only one plugin from this group.
135+
```
136+
137+
The plugin JAR and configured ADOT/provider/exporter must still be available as
138+
described below. Installing the JAR alone does not enable instrumentation.
139+
73140
## Installation
74141

75142
```xml
@@ -258,10 +325,11 @@ MyFunction:
258325
259326
With the layer and `DURABLE_EXECUTION_PLUGINS=otel-invocation` configured above, no OTel plugin dependency or registration code is required in the function artifact. The function can use its existing `DurableConfig`.
260327

261-
The OTel plugin JAR exposes two dynamic provider names:
328+
The OTel plugin JAR exposes three dynamic provider names:
262329

263330
| Provider name | Plugin | Trace model |
264331
|---------------|--------|-------------|
332+
| `otel` | `ExecutionOtelPlugin` | Workflow-rooted (default) |
265333
| `otel-invocation` | `InvocationOtelPlugin` | Invocation-rooted |
266334
| `otel-execution` | `ExecutionOtelPlugin` | Workflow-rooted |
267335

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
package software.amazon.lambda.durable.otel;
4+
5+
import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
6+
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
7+
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
8+
import software.amazon.lambda.durable.plugin.InvocationInfo;
9+
10+
/** Delegates a named ServiceLoader entry to its view's per-invocation factory. */
11+
final class DelegatingOtelPluginProvider implements DurableExecutionPluginProvider {
12+
private final String name;
13+
private final DurableExecutionPluginFactory factory;
14+
15+
DelegatingOtelPluginProvider(String name, DurableExecutionPluginFactory factory) {
16+
this.name = name;
17+
this.factory = factory;
18+
}
19+
20+
@Override
21+
public String getName() {
22+
return name;
23+
}
24+
25+
@Override
26+
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
27+
return factory.createPlugin(invocationInfo);
28+
}
29+
30+
@Override
31+
public String getExclusiveGroup() {
32+
return factory.getExclusiveGroup();
33+
}
34+
35+
/**
36+
* Names the selected entry and the view it loads, so an exclusive-group conflict reports the
37+
* {@code DURABLE_EXECUTION_PLUGINS} value the operator set rather than an object identity hash.
38+
*/
39+
@Override
40+
public String toString() {
41+
return getName() + " (" + factory + ")";
42+
}
43+
}

‎otel-plugin/src/main/java/software/amazon/lambda/durable/otel/ExecutionOtelPluginProvider.java‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
package software.amazon.lambda.durable.otel;
44

55
import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
6-
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
76
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
87
import software.amazon.lambda.durable.plugin.InvocationInfo;
98

@@ -15,20 +14,26 @@
1514
*/
1615
public final class ExecutionOtelPluginProvider implements DurableExecutionPluginProvider {
1716

18-
private final DurableExecutionPluginFactory factory = ExecutionOtelPlugin.factory();
17+
private final DurableExecutionPluginProvider delegate =
18+
new DelegatingOtelPluginProvider("otel-execution", ExecutionOtelPlugin.factory());
1919

2020
@Override
2121
public String getName() {
22-
return "otel-execution";
22+
return delegate.getName();
2323
}
2424

2525
@Override
2626
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
27-
return factory.createPlugin(invocationInfo);
27+
return delegate.createPlugin(invocationInfo);
2828
}
2929

3030
@Override
3131
public String getExclusiveGroup() {
32-
return factory.getExclusiveGroup();
32+
return delegate.getExclusiveGroup();
33+
}
34+
35+
@Override
36+
public String toString() {
37+
return delegate.toString();
3338
}
3439
}

‎otel-plugin/src/main/java/software/amazon/lambda/durable/otel/InvocationOtelPluginProvider.java‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
package software.amazon.lambda.durable.otel;
44

55
import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
6-
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
76
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
87
import software.amazon.lambda.durable.plugin.InvocationInfo;
98

@@ -16,20 +15,26 @@
1615
*/
1716
public final class InvocationOtelPluginProvider implements DurableExecutionPluginProvider {
1817

19-
private final DurableExecutionPluginFactory factory = InvocationOtelPlugin.factory();
18+
private final DurableExecutionPluginProvider delegate =
19+
new DelegatingOtelPluginProvider("otel-invocation", InvocationOtelPlugin.factory());
2020

2121
@Override
2222
public String getName() {
23-
return "otel-invocation";
23+
return delegate.getName();
2424
}
2525

2626
@Override
2727
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
28-
return factory.createPlugin(invocationInfo);
28+
return delegate.createPlugin(invocationInfo);
2929
}
3030

3131
@Override
3232
public String getExclusiveGroup() {
33-
return factory.getExclusiveGroup();
33+
return delegate.getExclusiveGroup();
34+
}
35+
36+
@Override
37+
public String toString() {
38+
return delegate.toString();
3439
}
3540
}
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
package software.amazon.lambda.durable.otel;
4+
5+
import static java.util.Objects.requireNonNull;
6+
7+
import io.opentelemetry.sdk.trace.SdkTracerProviderBuilder;
8+
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
9+
10+
/**
11+
* Selects the OpenTelemetry view to register with a durable handler. Execution mode is the default; invocation mode
12+
* places durable operations under their Lambda invocation instead of the Workflow span.
13+
*
14+
* <pre>{@code
15+
* DurableConfig.builder().withPlugins(OtelPlugin.factory()).build();
16+
* DurableConfig.builder().withPlugins(OtelPlugin.factory(OtelPlugin.Mode.INVOCATION)).build();
17+
* }</pre>
18+
*
19+
* <p>Each call returns a new factory of the selected view's type, carrying that view's configuration and
20+
* exclusive-group metadata; the returned factory then creates a fresh plugin for every invocation. Calls are not
21+
* memoized, so registering two of them puts two factories in one exclusive group and
22+
* {@code DurableConfig.builder().build()} rejects the configuration. The existing execution and invocation factory APIs
23+
* remain supported. Default configuration uses the global provider configured by ADOT or the application; exporters and
24+
* provider setup remain the application's responsibility.
25+
*
26+
* <p>{@link #factory()} covers the zero-configuration default. Every call that passes configuration or a provider
27+
* builder names its {@link Mode}, so the selected view is explicit wherever it is not the bare default.
28+
*/
29+
public final class OtelPlugin {
30+
private OtelPlugin() {}
31+
32+
/** The hierarchy used for durable operation spans. */
33+
public enum Mode {
34+
/** Durable operations are children of the Workflow span. */
35+
EXECUTION,
36+
/** Durable operations are children of their Invocation span. */
37+
INVOCATION
38+
}
39+
40+
/** @return an execution-view factory using the global provider and default configuration */
41+
public static DurableExecutionPluginFactory factory() {
42+
return factory(Mode.EXECUTION);
43+
}
44+
45+
/**
46+
* @param mode the view to select; must not be null
47+
* @return a factory using the global provider and default configuration
48+
*/
49+
public static DurableExecutionPluginFactory factory(Mode mode) {
50+
return factory(mode, OtelPluginConfig.defaults());
51+
}
52+
53+
/**
54+
* @param mode the view to select; must not be null
55+
* @param config configuration passed to the selected factory
56+
* @return a factory using the global provider
57+
*/
58+
public static DurableExecutionPluginFactory factory(Mode mode, OtelPluginConfig config) {
59+
return switch (requireNonNull(mode, "mode must not be null")) {
60+
case EXECUTION -> ExecutionOtelPlugin.factory(config);
61+
case INVOCATION -> InvocationOtelPlugin.factory(config);
62+
};
63+
}
64+
65+
/**
66+
* @param mode the view to select; must not be null
67+
* @param tracerProviderBuilder application-owned provider builder
68+
* @return a factory using default configuration
69+
*/
70+
public static DurableExecutionPluginFactory factory(Mode mode, SdkTracerProviderBuilder tracerProviderBuilder) {
71+
return factory(mode, tracerProviderBuilder, OtelPluginConfig.defaults());
72+
}
73+
74+
/**
75+
* @param mode the view to select; must not be null
76+
* @param tracerProviderBuilder application-owned provider builder
77+
* @param config configuration passed to the selected factory
78+
* @return the selected factory, retaining its registration metadata and per-invocation lifecycle
79+
*/
80+
public static DurableExecutionPluginFactory factory(
81+
Mode mode, SdkTracerProviderBuilder tracerProviderBuilder, OtelPluginConfig config) {
82+
return switch (requireNonNull(mode, "mode must not be null")) {
83+
case EXECUTION -> ExecutionOtelPlugin.factory(tracerProviderBuilder, config);
84+
case INVOCATION -> InvocationOtelPlugin.factory(tracerProviderBuilder, config);
85+
};
86+
}
87+
}
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
package software.amazon.lambda.durable.otel;
4+
5+
import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
6+
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
7+
import software.amazon.lambda.durable.plugin.InvocationInfo;
8+
9+
/**
10+
* Loads the default execution view when {@code DURABLE_EXECUTION_PLUGINS} contains {@code otel}.
11+
*
12+
* <p>{@code otel} and {@code otel-execution} load the same view through separate providers, so listing both puts two
13+
* factories in the {@code durable-otel-view} exclusive group and configuration is rejected at startup. Set exactly one
14+
* OTel entry name.
15+
*/
16+
public final class OtelPluginProvider implements DurableExecutionPluginProvider {
17+
private final DurableExecutionPluginProvider delegate =
18+
new DelegatingOtelPluginProvider("otel", OtelPlugin.factory());
19+
20+
@Override
21+
public String getName() {
22+
return delegate.getName();
23+
}
24+
25+
@Override
26+
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
27+
return delegate.createPlugin(invocationInfo);
28+
}
29+
30+
@Override
31+
public String getExclusiveGroup() {
32+
return delegate.getExclusiveGroup();
33+
}
34+
35+
@Override
36+
public String toString() {
37+
return delegate.toString();
38+
}
39+
}
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
software.amazon.lambda.durable.otel.InvocationOtelPluginProvider
22
software.amazon.lambda.durable.otel.ExecutionOtelPluginProvider
3+
software.amazon.lambda.durable.otel.OtelPluginProvider

0 commit comments

Comments
 (0)