Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 69 additions & 1 deletion otel-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,73 @@ user workers already admitted to their executor, and End does not mean all unawa
late-worker and mandatory large-result acknowledgment boundaries in [#787](https://github.com/aws/aws-durable-execution-sdk-java/issues/787)
remain outside this change.

## Select an OTel view

Import `OtelPlugin` to select the view through one API. Execution mode is the
default; invocation mode is an explicit choice:

```java
import software.amazon.lambda.durable.DurableConfig;
import software.amazon.lambda.durable.otel.OtelPlugin;

// Workflow-rooted operations (default).
var config = DurableConfig.builder().withPlugins(OtelPlugin.factory()).build();

// Invocation-rooted operations.
var invocationConfig = DurableConfig.builder()
.withPlugins(OtelPlugin.factory(OtelPlugin.Mode.INVOCATION))
.build();
```

`OtelPlugin.factory(OtelPlugin.Mode.EXECUTION)` explicitly selects execution mode.
Each call returns a *new* factory of the selected view's type, carrying that
view's configuration and exclusive-group metadata; the SDK then creates a fresh
plugin for each invocation, including concurrent invocations sharing a factory.

Calls are not memoized, so register exactly one. Passing two — for example
`withPlugins(OtelPlugin.factory(), OtelPlugin.factory())` — puts two factories in
the `durable-otel-view` exclusive group and `build()` throws
`IllegalArgumentException`.

Both modes accept the existing `OtelPluginConfig` and application-owned provider
builder. For example:

```java
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor;
import software.amazon.lambda.durable.otel.OtelPlugin;
import software.amazon.lambda.durable.otel.OtelPluginConfig;

var settings = OtelPluginConfig.builder().enableMdc(false).build();
var factory = OtelPlugin.factory(OtelPlugin.Mode.INVOCATION,
SdkTracerProvider.builder().addSpanProcessor(SimpleSpanProcessor.create(exporter)),
settings);
```

`OtelPlugin.factory()` is the zero-configuration default. Every overload that
takes configuration or a provider builder names its mode, so the selected view is
explicit wherever it is not the bare default; omit the builder to use the global
provider with the supplied settings. For an execution-view factory with your own
configuration, write `OtelPlugin.factory(OtelPlugin.Mode.EXECUTION, settings)`.
Existing `ExecutionOtelPlugin.factory(...)` and `InvocationOtelPlugin.factory(...)`
calls remain supported.

For loading without handler-side imports or registration, set
`DURABLE_EXECUTION_PLUGINS=otel`. This selects execution mode; `otel-execution`
is still supported and `otel-invocation` selects invocation mode.

**Set exactly one OTel entry name.** `otel` and `otel-execution` select the same
view, but they are separate providers, so listing both puts two factories in the
`durable-otel-view` exclusive group. For example,
`DURABLE_EXECUTION_PLUGINS=otel-execution,otel` fails at startup with:

```text
Conflicting plugin factories otel-execution (ExecutionOtelPlugin) and otel (ExecutionOtelPlugin) in exclusive group 'durable-otel-view'. Configure only one plugin from this group.
```

The plugin JAR and configured ADOT/provider/exporter must still be available as
described below. Installing the JAR alone does not enable instrumentation.

## Installation

```xml
Expand Down Expand Up @@ -258,10 +325,11 @@ MyFunction:

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`.

The OTel plugin JAR exposes two dynamic provider names:
The OTel plugin JAR exposes three dynamic provider names:

| Provider name | Plugin | Trace model |
|---------------|--------|-------------|
| `otel` | `ExecutionOtelPlugin` | Workflow-rooted (default) |
| `otel-invocation` | `InvocationOtelPlugin` | Invocation-rooted |
| `otel-execution` | `ExecutionOtelPlugin` | Workflow-rooted |

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package software.amazon.lambda.durable.otel;

import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
import software.amazon.lambda.durable.plugin.InvocationInfo;

/** Delegates a named ServiceLoader entry to its view's per-invocation factory. */
final class DelegatingOtelPluginProvider implements DurableExecutionPluginProvider {
private final String name;
private final DurableExecutionPluginFactory factory;

DelegatingOtelPluginProvider(String name, DurableExecutionPluginFactory factory) {
this.name = name;
this.factory = factory;
}

@Override
public String getName() {
return name;
}

@Override
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
return factory.createPlugin(invocationInfo);
}

@Override
public String getExclusiveGroup() {
return factory.getExclusiveGroup();
}

/**
* Names the selected entry and the view it loads, so an exclusive-group conflict reports the
* {@code DURABLE_EXECUTION_PLUGINS} value the operator set rather than an object identity hash.
*/
@Override
public String toString() {
return getName() + " (" + factory + ")";
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
package software.amazon.lambda.durable.otel;

import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
import software.amazon.lambda.durable.plugin.InvocationInfo;

Expand All @@ -15,20 +14,26 @@
*/
public final class ExecutionOtelPluginProvider implements DurableExecutionPluginProvider {

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

@Override
public String getName() {
return "otel-execution";
return delegate.getName();
}

@Override
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
return factory.createPlugin(invocationInfo);
return delegate.createPlugin(invocationInfo);
}

@Override
public String getExclusiveGroup() {
return factory.getExclusiveGroup();
return delegate.getExclusiveGroup();
}

@Override
public String toString() {
return delegate.toString();
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
package software.amazon.lambda.durable.otel;

import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
import software.amazon.lambda.durable.plugin.InvocationInfo;

Expand All @@ -16,20 +15,26 @@
*/
public final class InvocationOtelPluginProvider implements DurableExecutionPluginProvider {

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

@Override
public String getName() {
return "otel-invocation";
return delegate.getName();
}

@Override
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
return factory.createPlugin(invocationInfo);
return delegate.createPlugin(invocationInfo);
}

@Override
public String getExclusiveGroup() {
return factory.getExclusiveGroup();
return delegate.getExclusiveGroup();
}

@Override
public String toString() {
return delegate.toString();
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package software.amazon.lambda.durable.otel;

import static java.util.Objects.requireNonNull;

import io.opentelemetry.sdk.trace.SdkTracerProviderBuilder;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginFactory;

/**
* Selects the OpenTelemetry view to register with a durable handler. Execution mode is the default; invocation mode
* places durable operations under their Lambda invocation instead of the Workflow span.
*
* <pre>{@code
* DurableConfig.builder().withPlugins(OtelPlugin.factory()).build();
* DurableConfig.builder().withPlugins(OtelPlugin.factory(OtelPlugin.Mode.INVOCATION)).build();
* }</pre>
*
* <p>Each call returns a new factory of the selected view's type, carrying that view's configuration and
* exclusive-group metadata; the returned factory then creates a fresh plugin for every invocation. Calls are not
* memoized, so registering two of them puts two factories in one exclusive group and
* {@code DurableConfig.builder().build()} rejects the configuration. The existing execution and invocation factory APIs
* remain supported. Default configuration uses the global provider configured by ADOT or the application; exporters and
* provider setup remain the application's responsibility.
*
* <p>{@link #factory()} covers the zero-configuration default. Every call that passes configuration or a provider
* builder names its {@link Mode}, so the selected view is explicit wherever it is not the bare default.
*/
public final class OtelPlugin {
private OtelPlugin() {}

/** The hierarchy used for durable operation spans. */
public enum Mode {
/** Durable operations are children of the Workflow span. */
EXECUTION,
/** Durable operations are children of their Invocation span. */
INVOCATION
}

/** @return an execution-view factory using the global provider and default configuration */
public static DurableExecutionPluginFactory factory() {
return factory(Mode.EXECUTION);
}

/**
* @param mode the view to select; must not be null
* @return a factory using the global provider and default configuration
*/
public static DurableExecutionPluginFactory factory(Mode mode) {
return factory(mode, OtelPluginConfig.defaults());
}

/**
* @param mode the view to select; must not be null
* @param config configuration passed to the selected factory
* @return a factory using the global provider
*/
public static DurableExecutionPluginFactory factory(Mode mode, OtelPluginConfig config) {
return switch (requireNonNull(mode, "mode must not be null")) {
case EXECUTION -> ExecutionOtelPlugin.factory(config);
case INVOCATION -> InvocationOtelPlugin.factory(config);
};
}

/**
* @param mode the view to select; must not be null
* @param tracerProviderBuilder application-owned provider builder
* @return a factory using default configuration
*/
public static DurableExecutionPluginFactory factory(Mode mode, SdkTracerProviderBuilder tracerProviderBuilder) {
return factory(mode, tracerProviderBuilder, OtelPluginConfig.defaults());
}

/**
* @param mode the view to select; must not be null
* @param tracerProviderBuilder application-owned provider builder
* @param config configuration passed to the selected factory
* @return the selected factory, retaining its registration metadata and per-invocation lifecycle
*/
public static DurableExecutionPluginFactory factory(
Mode mode, SdkTracerProviderBuilder tracerProviderBuilder, OtelPluginConfig config) {
return switch (requireNonNull(mode, "mode must not be null")) {
case EXECUTION -> ExecutionOtelPlugin.factory(tracerProviderBuilder, config);
case INVOCATION -> InvocationOtelPlugin.factory(tracerProviderBuilder, config);
};
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package software.amazon.lambda.durable.otel;

import software.amazon.lambda.durable.plugin.DurableExecutionPlugin;
import software.amazon.lambda.durable.plugin.DurableExecutionPluginProvider;
import software.amazon.lambda.durable.plugin.InvocationInfo;

/**
* Loads the default execution view when {@code DURABLE_EXECUTION_PLUGINS} contains {@code otel}.
*
* <p>{@code otel} and {@code otel-execution} load the same view through separate providers, so listing both puts two
* factories in the {@code durable-otel-view} exclusive group and configuration is rejected at startup. Set exactly one
* OTel entry name.
*/
public final class OtelPluginProvider implements DurableExecutionPluginProvider {
Comment thread
zhongkechen marked this conversation as resolved.
Resolved
private final DurableExecutionPluginProvider delegate =
new DelegatingOtelPluginProvider("otel", OtelPlugin.factory());

@Override
public String getName() {
return delegate.getName();
}

@Override
public DurableExecutionPlugin createPlugin(InvocationInfo invocationInfo) {
return delegate.createPlugin(invocationInfo);
}

@Override
public String getExclusiveGroup() {
return delegate.getExclusiveGroup();
}

@Override
public String toString() {
return delegate.toString();
}
}
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
software.amazon.lambda.durable.otel.InvocationOtelPluginProvider
software.amazon.lambda.durable.otel.ExecutionOtelPluginProvider
software.amazon.lambda.durable.otel.OtelPluginProvider
Loading
Loading