Skip to content

(feat-351) add oltp headers #969

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hangweizhang wants to merge 1 commit into
base: main
Choose a base branch
from
Open

(feat-351) add oltp headers #969

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
56 changes: 56 additions & 0 deletions ...ns/agentscope-extensions-studio/src/main/java/io/agentscope/core/studio/StudioConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,9 @@
package io.agentscope.core.studio;

import java.time.Duration;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;

/**
Expand Down Expand Up @@ -48,6 +51,7 @@ public class StudioConfig {
private final int reconnectAttempts;
private final Duration reconnectDelay;
private final Duration reconnectMaxDelay;
private final Map<String, String> otlpHeaders;

private StudioConfig(Builder builder) {
this.studioUrl = builder.studioUrl;
Expand All @@ -59,6 +63,7 @@ private StudioConfig(Builder builder) {
this.reconnectAttempts = builder.reconnectAttempts;
this.reconnectDelay = builder.reconnectDelay;
this.reconnectMaxDelay = builder.reconnectMaxDelay;
this.otlpHeaders = Collections.unmodifiableMap(new HashMap<>(builder.otlpHeaders));
}

public static Builder builder() {
Expand Down Expand Up @@ -146,6 +151,18 @@ public Duration getReconnectMaxDelay() {
return reconnectMaxDelay;
}

/**
* Gets the OTLP headers for authentication.
*
* <p>These headers are included in OTLP HTTP requests to the tracing endpoint.
* Useful for authentication with systems like Langfuse that require custom headers.
*
* @return an unmodifiable map of header names to values (default: empty map)
*/
public Map<String, String> getOtlpHeaders() {
return otlpHeaders;
}

public static class Builder {
private String studioUrl = "http://localhost:3000";
private String tracingUrl;
Expand All @@ -156,6 +173,7 @@ public static class Builder {
private int reconnectAttempts = 3;
private Duration reconnectDelay = Duration.ofSeconds(1);
private Duration reconnectMaxDelay = Duration.ofSeconds(5);
private Map<String, String> otlpHeaders = new HashMap<>();

public Builder studioUrl(String studioUrl) {
this.studioUrl = studioUrl;
Expand Down Expand Up @@ -202,6 +220,44 @@ public Builder reconnectMaxDelay(Duration reconnectMaxDelay) {
return this;
}

/**
* Adds a single OTLP header for authentication.
*
* <p>This header will be included in OTLP HTTP requests to the tracing endpoint.
* Useful for systems like Langfuse that require authentication headers.
*
* <p>Example for Langfuse:
* <pre>{@code
* StudioConfig config = StudioConfig.builder()
* .studioUrl("https://cloud.langfuse.com")
* .tracingUrl("https://cloud.langfuse.com/api/public/otel/v1/traces")
* .addOtlpHeader("Authorization", "Basic " + base64Credentials)
* .build();
* }</pre>
*
* @param key The header name (e.g., "Authorization")
* @param value The header value (e.g., "Basic dXNlcjpwYXNz")
* @return This builder
*/
public Builder addOtlpHeader(String key, String value) {
Copy link
Copy Markdown
Collaborator

@LearningGp LearningGp Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest adding a null check here.

this.otlpHeaders.put(key, value);
return this;
}

/**
* Sets all OTLP headers for authentication.
*
* <p>These headers will be included in OTLP HTTP requests to the tracing endpoint.
* This method replaces any previously added headers.
*
* @param headers Map of header names to values
* @return This builder
*/
public Builder otlpHeaders(Map<String, String> headers) {
this.otlpHeaders = new HashMap<>(headers);
return this;
}

public StudioConfig build() {
if (tracingUrl == null) {
tracingUrl = studioUrl + "/v1/traces";
Expand Down
44 changes: 43 additions & 1 deletion ...s/agentscope-extensions-studio/src/main/java/io/agentscope/core/studio/StudioManager.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,45 @@ public Builder reconnectAttempts(int reconnectAttempts) {
return this;
}

/**
* Adds a single OTLP header for authentication.
*
* <p>This header will be included in OTLP HTTP requests to the tracing endpoint.
* Useful for systems like Langfuse that require authentication headers.
*
* <p>Example for Langfuse:
* <pre>{@code
* StudioManager.init()
* .studioUrl("https://cloud.langfuse.com")
* .tracingUrl("https://cloud.langfuse.com/api/public/otel/v1/traces")
* .addOtlpHeader("Authorization", "Basic " + base64Credentials)
* .initialize()
* .block();
* }</pre>
*
* @param key The header name (e.g., "Authorization")
* @param value The header value (e.g., "Basic dXNlcjpwYXNz")
* @return This builder
*/
public Builder addOtlpHeader(String key, String value) {
Copy link
Copy Markdown
Collaborator

@LearningGp LearningGp Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto

configBuilder.addOtlpHeader(key, value);
return this;
}

/**
* Sets all OTLP headers for authentication.
*
* <p>These headers will be included in OTLP HTTP requests to the tracing endpoint.
* This method replaces any previously added headers.
*
* @param headers Map of header names to values
* @return This builder
*/
public Builder otlpHeaders(java.util.Map<String, String> headers) {
Copy link
Copy Markdown
Collaborator

@LearningGp LearningGp Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prefer import statements for consistency with the rest of the project.

configBuilder.otlpHeaders(headers);
return this;
}

/**
* Initializes Studio integration.
*
Expand Down Expand Up @@ -255,7 +294,10 @@ public Mono<Void> initialize() {
traceEndpoint = config.getTracingUrl();
}
TracerRegistry.register(
TelemetryTracer.builder().endpoint(traceEndpoint).build());
TelemetryTracer.builder()
.endpoint(traceEndpoint)
.headers(config.getOtlpHeaders())
.build());
})
.doOnError(e -> logger.error("Failed to initialize Studio", e))
.onErrorResume(
Expand Down
142 changes: 142 additions & 0 deletions ...gentscope-extensions-studio/src/test/java/io/agentscope/core/studio/StudioConfigTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@
import static org.junit.jupiter.api.Assertions.assertTrue;

import java.time.Duration;
import java.util.HashMap;
import java.util.Map;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

Expand Down Expand Up @@ -129,4 +131,144 @@ void testBuilderEdgeCases() {
assertEquals(Duration.ofHours(1), config2.getReconnectDelay());
assertEquals(Duration.ofHours(24), config2.getReconnectMaxDelay());
}

@Test
@DisplayName("Builder with addOtlpHeader should create config with single header")
void testBuilderWithAddOtlpHeader() {
StudioConfig config =
StudioConfig.builder()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.addOtlpHeader("Authorization", "Basic dGVzdDp0ZXN0")
.build();

assertNotNull(config.getOtlpHeaders());
assertEquals(1, config.getOtlpHeaders().size());
assertEquals("Basic dGVzdDp0ZXN0", config.getOtlpHeaders().get("Authorization"));
}

@Test
@DisplayName("Builder with multiple addOtlpHeader calls should accumulate headers")
void testBuilderWithMultipleAddOtlpHeaders() {
StudioConfig config =
StudioConfig.builder()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.addOtlpHeader("Authorization", "Basic dGVzdDp0ZXN0")
.addOtlpHeader("X-Custom-Header", "custom-value")
.addOtlpHeader("X-Trace-Id", "trace-123")
.build();

assertNotNull(config.getOtlpHeaders());
assertEquals(3, config.getOtlpHeaders().size());
assertEquals("Basic dGVzdDp0ZXN0", config.getOtlpHeaders().get("Authorization"));
assertEquals("custom-value", config.getOtlpHeaders().get("X-Custom-Header"));
assertEquals("trace-123", config.getOtlpHeaders().get("X-Trace-Id"));
}

@Test
@DisplayName("Builder with otlpHeaders map should create config with all headers")
void testBuilderWithOtlpHeadersMap() {
Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "Bearer token123");
headers.put("X-Api-Key", "api-key-value");

StudioConfig config =
StudioConfig.builder()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.otlpHeaders(headers)
.build();

assertNotNull(config.getOtlpHeaders());
assertEquals(2, config.getOtlpHeaders().size());
assertEquals("Bearer token123", config.getOtlpHeaders().get("Authorization"));
assertEquals("api-key-value", config.getOtlpHeaders().get("X-Api-Key"));
}

@Test
@DisplayName("Default config should have empty OTLP headers")
void testDefaultOtlpHeadersEmpty() {
StudioConfig config =
StudioConfig.builder()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.build();

assertNotNull(config.getOtlpHeaders());
assertTrue(config.getOtlpHeaders().isEmpty());
}

@Test
@DisplayName("OTLP headers should be immutable after build")
void testOtlpHeadersImmutability() {
StudioConfig config =
StudioConfig.builder()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.addOtlpHeader("Authorization", "Basic dGVzdDp0ZXN0")
.build();

Map<String, String> headers = config.getOtlpHeaders();

try {
headers.put("X-New-Header", "should-fail");
// If we reach here, the map is mutable (which is wrong)
assertTrue(false, "Headers map should be immutable");
} catch (UnsupportedOperationException e) {
// Expected behavior - map is immutable
assertTrue(true);
Copy link
Copy Markdown
Collaborator

@LearningGp LearningGp Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest using assertThrows here.

}
}

@Test
@DisplayName("Combining otlpHeaders and addOtlpHeader should work correctly")
void testCombiningHeaderMethods() {
Map<String, String> initialHeaders = new HashMap<>();
initialHeaders.put("X-Initial", "initial-value");

StudioConfig config =
StudioConfig.builder()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.otlpHeaders(initialHeaders)
.addOtlpHeader("X-Additional", "additional-value")
.build();

assertNotNull(config.getOtlpHeaders());
assertEquals(2, config.getOtlpHeaders().size());
assertEquals("initial-value", config.getOtlpHeaders().get("X-Initial"));
assertEquals("additional-value", config.getOtlpHeaders().get("X-Additional"));
}

@Test
@DisplayName("Langfuse-style authentication should work correctly")
void testLangfuseStyleAuthentication() {
String publicKey = "pk-lf-test";
String secretKey = "sk-lf-test";
String base64Credentials =
java.util.Base64.getEncoder()
.encodeToString((publicKey + ":" + secretKey).getBytes());

StudioConfig config =
StudioConfig.builder()
.studioUrl("https://cloud.langfuse.com")
.tracingUrl("https://cloud.langfuse.com/api/public/otel/v1/traces")
.project("LangfuseProject")
.runName("langfuse_run")
.addOtlpHeader("Authorization", "Basic " + base64Credentials)
.build();

assertNotNull(config.getOtlpHeaders());
assertEquals(1, config.getOtlpHeaders().size());
assertTrue(config.getOtlpHeaders().get("Authorization").startsWith("Basic "));
assertEquals(
"https://cloud.langfuse.com/api/public/otel/v1/traces", config.getTracingUrl());
}
}
72 changes: 72 additions & 0 deletions ...entscope-extensions-studio/src/test/java/io/agentscope/core/studio/StudioManagerTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;

import java.util.HashMap;
import java.util.Map;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
Expand Down Expand Up @@ -125,4 +127,74 @@ void testShutdownIdempotent() {
assertNull(StudioManager.getClient());
assertFalse(StudioManager.isInitialized());
}

@Test
@DisplayName("Builder should support addOtlpHeader method")
void testBuilderAddOtlpHeader() {
StudioManager.Builder builder =
StudioManager.init()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.addOtlpHeader("Authorization", "Basic dGVzdDp0ZXN0");

assertNotNull(builder);
}

@Test
@DisplayName("Builder should support otlpHeaders method with map")
void testBuilderOtlpHeadersMap() {
Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "Bearer token123");
headers.put("X-Api-Key", "api-key-value");

StudioManager.Builder builder =
StudioManager.init()
.studioUrl("http://localhost:3000")
.project("TestProject")
.runName("test_run")
.otlpHeaders(headers);

assertNotNull(builder);
}

@Test
@DisplayName("Builder should support combining header methods with other configuration")
void testBuilderCombiningHeadersWithOtherConfig() {
Map<String, String> headers = new HashMap<>();
headers.put("X-Initial", "initial");

StudioManager.Builder builder =
StudioManager.init()
.studioUrl("https://cloud.langfuse.com")
.tracingUrl("https://cloud.langfuse.com/api/public/otel/v1/traces")
.project("LangfuseProject")
.runName("langfuse_run")
.maxRetries(5)
.reconnectAttempts(3)
.otlpHeaders(headers)
.addOtlpHeader("Authorization", "Basic credentials");

assertNotNull(builder);
}

@Test
@DisplayName("Builder should support Langfuse-style configuration")
void testBuilderLangfuseConfiguration() {
String publicKey = "pk-lf-test";
String secretKey = "sk-lf-test";
String base64Credentials =
java.util.Base64.getEncoder()
.encodeToString((publicKey + ":" + secretKey).getBytes());

StudioManager.Builder builder =
StudioManager.init()
.studioUrl("https://cloud.langfuse.com")
.tracingUrl("https://cloud.langfuse.com/api/public/otel/v1/traces")
.project("LangfuseProject")
.runName("langfuse_run")
.addOtlpHeader("Authorization", "Basic " + base64Credentials);

assertNotNull(builder);
}
}
Loading