diff --git a/.github/workflows/azure-openai-java-docs.yml b/.github/workflows/azure-openai-java-docs.yml new file mode 100644 index 000000000..4f25bebfd --- /dev/null +++ b/.github/workflows/azure-openai-java-docs.yml @@ -0,0 +1,44 @@ +name: Azure OpenAI Java documentation + +on: + pull_request: + branches: [main] + paths: + - src/pages/docs/integrations/traceai/java/llm-providers.mdx + - scripts/azure-openai-java* + - .github/workflows/azure-openai-java-docs.yml + +permissions: + contents: read + +jobs: + otlp-contract: + name: Azure OTLP contract (Java ${{ matrix.java }}) + runs-on: ubuntu-latest + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + java: ['17', '21'] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-java@v4 + with: + distribution: temurin + java-version: ${{ matrix.java }} + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + - uses: gradle/actions/setup-gradle@v4 + with: + gradle-version: '8.14.3' + - name: Install OTLP decoder + run: python -m pip install opentelemetry-proto==1.38.0 + - name: Run exact Maven and Gradle examples with synthetic Azure and captured OTLP + run: python -I scripts/azure-openai-java-wire.py --work "$RUNNER_TEMP/azure-java" + - uses: actions/upload-artifact@v4 + if: always() + with: + name: azure-java-${{ matrix.java }} + path: ${{ runner.temp }}/azure-java/evidence + if-no-files-found: error diff --git a/scripts/azure-openai-java-wire.py b/scripts/azure-openai-java-wire.py new file mode 100644 index 000000000..bc53a9f59 --- /dev/null +++ b/scripts/azure-openai-java-wire.py @@ -0,0 +1,205 @@ +"""Run the exact Azure Java page example against loopback Azure and OTLP servers. + +Requires JDK 17+, Maven, Gradle 8.14.3, openssl and opentelemetry-proto==1.38.0. +Only synthetic credentials are passed to the example. No vendor account is used. +""" +import argparse +import gzip +import json +import os +from pathlib import Path +import re +import shutil +import ssl +import subprocess +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from threading import Thread + +from google.protobuf.json_format import MessageToDict +from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest + +PAGE = Path(__file__).resolve().parents[1] / 'src/pages/docs/integrations/traceai/java/llm-providers.mdx' +INPUT = [{'role': 'user', 'content': 'What is the capital of France?'}] +OUTPUT = [{'role': 'assistant', 'content': 'Paris'}] +MODEL = 'gpt-4o-mini-2024-07-18' + + +def attributes(span): + return {a['key']: next(iter(a['value'].values())) for a in span['attributes']} + + +def assert_capture(page, capture): + spans = [span for export in capture['exports'] + for resource in export.get('resource_spans', []) + for scope in resource.get('scope_spans', []) for span in scope.get('spans', [])] + assert len(spans) == 1, f'Expected one semantic span, got {len(spans)}' + span = spans[0] + assert span['name'] == 'Azure OpenAI Chat Completion' + assert span['status']['code'] == 'STATUS_CODE_OK' + attrs = attributes(span) + expected = { + 'gen_ai.provider.name': 'azure', + 'gen_ai.request.model': 'chat-deploy', + 'gen_ai.response.model': MODEL, + 'gen_ai.usage.input_tokens': '9', + 'gen_ai.usage.output_tokens': '3', + 'gen_ai.usage.total_tokens': '12', + 'gen_ai.input.messages': INPUT, + 'gen_ai.output.messages': OUTPUT, + 'output.value': 'Paris', + } + reference = page.split('### Azure OpenAI attributes\n')[1].split('\n### ')[0] + documented = re.findall(r'^\| `([^`]+)` \|', reference, re.M) + assert set(documented) == set(expected), f'Documented keys changed: {documented}' + for key, value in expected.items(): + actual = json.loads(attrs[key]) if key.endswith('.messages') else attrs[key] + assert actual == value, (key, actual, value) + assert not any(key.startswith('llm.') for key in attrs) + assert attrs['fi.span.kind'] == 'LLM' + # Pin the released SDK's serialization limitation, not a mocked tracer. + for key, class_name in [('fi.raw_input', 'ChatCompletionsOptions'), ('fi.raw_output', 'ChatCompletions')]: + assert re.fullmatch(r'com\.azure\.ai\.openai\.models\.' + class_name + r'@[0-9a-f]+', attrs[key]), (key, attrs[key]) + try: + json.loads(attrs[key]) + except json.JSONDecodeError: + pass + else: + raise AssertionError(f'{key} is now JSON; revisit the versioned documentation') + assert 'not full request/response JSON' in reference + assert 'Do not rely on the raw fields for payload replay' in reference + assert len(capture['requests']) == 1 + request = capture['requests'][0] + assert request['path'].startswith('/openai/deployments/chat-deploy/chat/completions?api-version=') + assert request['body']['messages'] == INPUT + assert request['api_key'] == 'synthetic-azure' + assert len(capture['export_headers']) == 1 + headers = capture['export_headers'][0] + assert headers['x-api-key'] == 'synthetic-fi-api' + assert headers['x-secret-key'] == 'synthetic-fi-secret' + assert headers['content-type'].startswith('application/x-protobuf') + + +def run(command, cwd, env, log): + result = subprocess.run(command, cwd=cwd, env=env, capture_output=True, text=True, timeout=600) + log.write_text(result.stdout + result.stderr) + if result.returncode: + raise RuntimeError(f'Command failed ({result.returncode}); see {log}') + return result.stdout + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--work', required=True, type=Path) + parser.add_argument('--page', type=Path, default=PAGE) + parser.add_argument('--build-tool', choices=['maven', 'gradle', 'both'], default='both') + args = parser.parse_args() + work = args.work.resolve() + evidence = work / 'evidence' + source = work / 'project/src/main/java' + source.mkdir(parents=True, exist_ok=True) + evidence.mkdir(parents=True, exist_ok=True) + project = source.parents[2] + page = args.page.read_text() + azure = page.split('## Azure OpenAI\n')[1].split('\n## ')[0] + java = re.search(r'```java\n(.*?)```', azure, re.S)[1] + imports = '\n'.join(line for line in java.splitlines() if line.startswith('import ')) + body = '\n'.join(line for line in java.splitlines() if not line.startswith('import ')) + (source / 'Example.java').write_text(imports + '\npublic class Example { public static void main(String[] args) {\n' + body + '\n}}\n') + maven_deps = re.search(r'```xml Maven\n(.*?)```', azure, re.S)[1] + gradle_deps = re.search(r'```groovy Gradle\n(.*?)```', azure, re.S)[1] + (project / 'pom.xml').write_text(''' +4.0.0testazure-docs1.0 +17''' + + maven_deps + '''org.apache.maven.plugins +maven-compiler-plugin3.13.0''') + (project / 'settings.gradle').write_text("rootProject.name = 'azure-docs'\n") + (project / 'build.gradle').write_text("plugins { id 'application' }\nrepositories { mavenCentral() }\ndependencies {\n" + + gradle_deps + "}\napplication { mainClass = 'Example' }\n") + env = {key: os.environ[key] for key in ['PATH', 'JAVA_HOME', 'HOME', 'TMPDIR'] if key in os.environ} + assert env.get('JAVA_HOME'), 'Set JAVA_HOME to the JDK under test' + run(['java', '-version'], project, env, evidence / 'java-version.log') + tls_dir = work / 'tls' + tls_dir.mkdir(exist_ok=True) + key, cert, trust = [tls_dir / name for name in ['mock.key', 'mock.crt', 'truststore']] + run(['openssl', 'req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-keyout', str(key), '-out', str(cert), + '-days', '1', '-subj', '/CN=localhost', '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1'], + project, env, evidence / 'certificate.log') + shutil.copyfile(Path(env['JAVA_HOME']) / 'lib/security/cacerts', trust) + run(['keytool', '-importcert', '-noprompt', '-alias', 'azure-docs-mock', '-file', str(cert), + '-keystore', str(trust), '-storepass', 'changeit'], project, env, evidence / 'truststore.log') + capture = {'exports': [], 'requests': [], 'export_headers': []} + + class Handler(BaseHTTPRequestHandler): + def log_message(self, *args): + pass + + def do_POST(self): + data = self.rfile.read(int(self.headers.get('Content-Length', '0'))) + if self.headers.get('Content-Encoding') == 'gzip': + data = gzip.decompress(data) + if self.path == '/tracer/v1/traces': + decoded = MessageToDict(ExportTraceServiceRequest.FromString(data), preserving_proto_field_name=True) + capture['exports'].append(decoded) + capture['export_headers'].append({k.lower(): v for k, v in self.headers.items()}) + self.send_response(200) + self.send_header('Content-Type', 'application/x-protobuf') + self.send_header('Content-Length', '0') + self.end_headers() + return + if not self.path.startswith('/openai/deployments/chat-deploy/chat/completions?'): + self.send_error(404) + return + capture['requests'].append({'path': self.path, 'body': json.loads(data), 'api_key': self.headers.get('api-key')}) + response = json.dumps({ + 'id': 'chatcmpl-synthetic', 'object': 'chat.completion', 'created': 1700000000, 'model': MODEL, + 'choices': [{'index': 0, 'message': OUTPUT[0], 'finish_reason': 'stop'}], + 'usage': {'prompt_tokens': 9, 'completion_tokens': 3, 'total_tokens': 12}, + }).encode() + self.send_response(200) + self.send_header('Content-Type', 'application/json') + self.send_header('Content-Length', str(len(response))) + self.end_headers() + self.wfile.write(response) + + otlp = ThreadingHTTPServer(('127.0.0.1', 0), Handler) + azure_server = ThreadingHTTPServer(('127.0.0.1', 0), Handler) + tls = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER) + tls.load_cert_chain(cert, key) + azure_server.socket = tls.wrap_socket(azure_server.socket, server_side=True) + threads = [Thread(target=server.serve_forever, daemon=True) for server in [otlp, azure_server]] + for thread in threads: + thread.start() + env.update({ + 'FI_BASE_URL': f'http://127.0.0.1:{otlp.server_port}', + 'FI_API_KEY': 'synthetic-fi-api', 'FI_SECRET_KEY': 'synthetic-fi-secret', 'FI_PROJECT_NAME': 'azure-docs', + 'AZURE_OPENAI_ENDPOINT': f'https://localhost:{azure_server.server_port}', + 'AZURE_OPENAI_API_KEY': 'synthetic-azure', 'AZURE_OPENAI_DEPLOYMENT': 'chat-deploy', + 'JAVA_TOOL_OPTIONS': f'-Djavax.net.ssl.trustStore={trust} -Djavax.net.ssl.trustStorePassword=changeit', + }) + tools = ['maven', 'gradle'] if args.build_tool == 'both' else [args.build_tool] + try: + for tool in tools: + for values in capture.values(): + values.clear() + if tool == 'maven': + run(['mvn', '-B', '-ntp', 'package', 'dependency:build-classpath', '-Dmdep.outputFile=cp.txt'], + project, env, evidence / 'maven-build.log') + classpath = str(project / 'target/classes') + os.pathsep + (project / 'cp.txt').read_text().strip() + command = ['java', '-cp', classpath, 'Example'] + else: + command = ['gradle', '--no-daemon', 'run'] + output = run(command, project, env, evidence / f'{tool}-run.log') + (evidence / f'{tool}-capture.json').write_text(json.dumps(capture, indent=2) + '\n') + assert 'Paris' in output + assert_capture(page, capture) + print(f'PASS {tool}: exact page example, captured OTLP keys/messages/usage, raw serialization limitation', flush=True) + finally: + for server in [otlp, azure_server]: + server.shutdown() + server.server_close() + for thread in threads: + thread.join(timeout=5) + + +if __name__ == '__main__': + main() diff --git a/scripts/azure-openai-java.test.mjs b/scripts/azure-openai-java.test.mjs new file mode 100644 index 000000000..24c602366 --- /dev/null +++ b/scripts/azure-openai-java.test.mjs @@ -0,0 +1,53 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; + +const page = readFileSync(new URL('../src/pages/docs/integrations/traceai/java/llm-providers.mdx', import.meta.url), 'utf8'); +const azure = page.split('## Azure OpenAI\n')[1]?.split('\n## ')[0]; +const azureAttributes = page.split('### Azure OpenAI attributes\n')[1]?.split('\n### ')[0]; + +test('Azure Java reference uses released keys and scopes legacy attributes separately', () => { + assert.ok(azureAttributes, 'Azure has a version-scoped attribute reference'); + const keys = [...azureAttributes.matchAll(/^\| `([^`]+)` \|/gm)].map(match => match[1]); + assert.deepEqual(keys, [ + 'gen_ai.provider.name', 'gen_ai.request.model', 'gen_ai.response.model', + 'gen_ai.usage.input_tokens', 'gen_ai.usage.output_tokens', 'gen_ai.usage.total_tokens', + 'gen_ai.input.messages', 'gen_ai.output.messages', 'output.value', + ]); + assert.match(azureAttributes, /traceai-java-azure-openai:1\.0\.0/); + assert.match(azure, /\(#azure-openai-attributes\)/); + const legacy = page.split('### Legacy snapshot provider attributes\n')[1]; + assert.ok(legacy); + assert.match(legacy, /not the released Azure OpenAI setup/); + assert.doesNotMatch(azureAttributes, /`llm\./); +}); + +test('Azure raw payload fields do not promise JSON or replay support', () => { + assert.ok(azureAttributes); + assert.match(azureAttributes, /`fi\.raw_input` and `fi\.raw_output` can contain Java object strings/); + assert.match(azureAttributes, /not full request\/response JSON/); + assert.match(azureAttributes, /structured message, model, and usage fields/); + assert.match(azureAttributes, /Do not rely on the raw fields for payload replay/); + assert.doesNotMatch(page, /Full request\/response as JSON/); +}); + +test('Azure Java setup uses released coordinates and declares the provided Azure SDK', () => { + assert.ok(azure, 'Azure OpenAI section exists'); + assert.match(azure, /com\.futureagi<\/groupId>\s*traceai-java-azure-openai<\/artifactId>\s*1\.0\.0<\/version>/); + assert.match(azure, /com\.futureagi:traceai-java-azure-openai:1\.0\.0/); + assert.match(azure, /com\.azure<\/groupId>\s*azure-ai-openai<\/artifactId>\s*1\.0\.0-beta\.16<\/version>/); + assert.match(azure, /com\.azure:azure-ai-openai:1\.0\.0-beta\.16/); + assert.doesNotMatch(azure, /main-SNAPSHOT|com\.github\.future-agi/); +}); + +test('Azure Java scope distinguishes blocking calls, unwrap, and upstream migration', () => { + assert.match(azure, /synchronous|blocking/); + assert.match(azure, /streaming/); + assert.match(azure, /OpenAIAsyncClient/); + assert.match(azure, /unwrap\(\)/); + assert.match(azure, /not (?:traced|instrumented|a drop-in)/); + assert.match(azure, /github\.com\/Azure\/azure-sdk-for-java/); + assert.match(azure, /AZURE_OPENAI_DEPLOYMENT/); + assert.match(azure, /TraceAI\.shutdown\(\)/); + assert.doesNotMatch(azure, /all API calls|handles all message types/); +}); diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index d09eb7390..504180600 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -1,3 +1,4 @@ +import './azure-openai-java.test.mjs'; import './langsmith-page.test.mjs'; import './vercel-platform-page.test.mjs'; import './scalekit-page.test.mjs'; diff --git a/src/pages/docs/integrations/traceai/java/llm-providers.mdx b/src/pages/docs/integrations/traceai/java/llm-providers.mdx index f332e76d9..d7ac2e3fe 100644 --- a/src/pages/docs/integrations/traceai/java/llm-providers.mdx +++ b/src/pages/docs/integrations/traceai/java/llm-providers.mdx @@ -100,24 +100,40 @@ The [Google GenAI example above](#google-genai) uses a Gemini API key. It is not ## Azure OpenAI -Wraps `com.azure.ai.openai.OpenAIClient` from the Azure SDK. +Trace synchronous chat completions, embeddings, and legacy text completions from existing applications using `com.azure.ai.openai.OpenAIClient`. + +Microsoft [no longer updates this Azure SDK client in its current form](https://github.com/Azure/azure-sdk-for-java/blob/5bf21284d74c27d37110169721e0ef2b6de4bc83/sdk/openai/azure-ai-openai/README.md). For new OpenAI features, follow Microsoft's guidance to the official OpenAI Java SDK. That SDK uses different client types; this wrapper is not a drop-in adapter for it. + +### Install the legacy client and wrapper + +Use Java 17 or later and add both dependencies from Maven Central. The wrapper declares the Azure SDK as a provided dependency, so your application must include it explicitly. ```xml Maven - com.github.future-agi.traceAI + com.futureagi traceai-java-azure-openai - main-SNAPSHOT + 1.0.0 + + + com.azure + azure-ai-openai + 1.0.0-beta.16 ``` ```groovy Gradle -implementation 'com.github.future-agi.traceAI:traceai-java-azure-openai:main-SNAPSHOT' +implementation 'com.futureagi:traceai-java-azure-openai:1.0.0' +implementation 'com.azure:azure-ai-openai:1.0.0-beta.16' ``` +### Trace a chat completion + +Set `AZURE_OPENAI_ENDPOINT` to your Azure resource endpoint, `AZURE_OPENAI_API_KEY` to its API key, and `AZURE_OPENAI_DEPLOYMENT` to your chat deployment name. A deployment name can differ from the underlying model name. Configure your Future AGI credentials using the [Java SDK setup](/docs/integrations/traceai/java). + ```java import ai.traceai.TraceAI; import ai.traceai.azure.openai.TracedAzureOpenAIClient; @@ -126,36 +142,42 @@ import com.azure.ai.openai.OpenAIClientBuilder; import com.azure.core.credential.AzureKeyCredential; import com.azure.ai.openai.models.ChatCompletionsOptions; import com.azure.ai.openai.models.ChatRequestUserMessage; -import com.azure.ai.openai.models.EmbeddingsOptions; import java.util.List; TraceAI.initFromEnvironment(); +try { + OpenAIClient client = new OpenAIClientBuilder() + .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT")) + .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY"))) + .buildClient(); + TracedAzureOpenAIClient traced = new TracedAzureOpenAIClient(client); + + var options = new ChatCompletionsOptions(List.of( + new ChatRequestUserMessage("What is the capital of France?") + )); + var response = traced.getChatCompletions( + System.getenv("AZURE_OPENAI_DEPLOYMENT"), options); + System.out.println(response.getChoices().get(0).getMessage().getContent()); +} finally { + TraceAI.shutdown(); +} +``` -OpenAIClient client = new OpenAIClientBuilder() - .endpoint(System.getenv("AZURE_OPENAI_ENDPOINT")) - .credential(new AzureKeyCredential(System.getenv("AZURE_OPENAI_API_KEY"))) - .buildClient(); +For a long-running application, initialize TraceAI once and call `TraceAI.shutdown()` when the application exits, not after each request. -TracedAzureOpenAIClient traced = new TracedAzureOpenAIClient(client); +Open your project in Future AGI to inspect the **Azure OpenAI Chat Completion** span, its deployment name, response model, messages, and token usage. See the [Azure OpenAI attributes](#azure-openai-attributes) below for the exported keys. Content capture follows the controls described above. -// Chat completions - first arg is deployment name -var chatOptions = new ChatCompletionsOptions(List.of( - new ChatRequestUserMessage("What is the capital of France?") -)); -var response = traced.getChatCompletions("gpt-4o-mini", chatOptions); -System.out.println(response.getChoices().get(0).getMessage().getContent()); +### Supported operations -// Embeddings -var embeddingOptions = new EmbeddingsOptions(List.of("Hello world")); -var embeddings = traced.getEmbeddings("text-embedding-3-small", embeddingOptions); -``` +| Wrapper method | Span | Kind | +| --- | --- | --- | +| `getChatCompletions()` | Azure OpenAI Chat Completion | LLM | +| `getEmbeddings()` | Azure OpenAI Embedding | EMBEDDING | +| `getCompletions()` | Azure OpenAI Completion | LLM, legacy text API | -**Spans created:** -- `getChatCompletions()` - "Azure OpenAI Chat Completion" (LLM) -- `getEmbeddings()` - "Azure OpenAI Embedding" (EMBEDDING) -- `getCompletions()` - "Azure OpenAI Completion" (LLM, legacy API) +These three methods are blocking calls. Use a deployment appropriate to the operation; an embeddings request needs an embeddings deployment. -Azure OpenAI captures tool call attributes when the model invokes tools, and handles all message types (System, User, Assistant, Tool, Function). +Streaming, `OpenAIAsyncClient`, Responses, audio, images, and files are not traced by this wrapper. `unwrap()` returns the original client without this wrapper's instrumentation. Calling a streaming method through `unwrap()` does not create a semantic LLM span, even if separate Azure HTTP tracing is enabled. Keep calls on the wrapper's supported methods when you need these traces; do not switch to `traceai-java-openai` expecting equivalent Azure or streaming behavior. --- @@ -253,15 +275,37 @@ Like Anthropic, the reflection approach means the client and request objects are ## Common span attributes -Depending on the provider and operation, spans can include these attributes: +### Azure OpenAI attributes + +The chat example using `traceai-java-azure-openai:1.0.0` and `azure-ai-openai:1.0.0-beta.16` exports these keys. Response model and token usage depend on the service response; message and output fields follow your content-capture settings. + +| Attribute | Description | +| --- | --- | +| `gen_ai.provider.name` | `azure` | +| `gen_ai.request.model` | Deployment name passed to the wrapper, which can differ from the model name | +| `gen_ai.response.model` | Model name returned by Azure | +| `gen_ai.usage.input_tokens` | Input token count | +| `gen_ai.usage.output_tokens` | Output token count | +| `gen_ai.usage.total_tokens` | Total token count | +| `gen_ai.input.messages` | JSON-encoded input messages with role and content | +| `gen_ai.output.messages` | JSON-encoded output messages with role and content | +| `output.value` | Text from the first response choice | + + +With these versions, `fi.raw_input` and `fi.raw_output` can contain Java object strings such as `com.azure.ai.openai.models.ChatCompletionsOptions@...`, not full request/response JSON. Use the structured message, model, and usage fields above for inspection and filtering. Do not rely on the raw fields for payload replay. + + +### Legacy snapshot provider attributes + +The following table applies to the legacy `main-SNAPSHOT` integrations for Google GenAI, Ollama, and Watsonx, not the released Azure OpenAI setup above. Attributes vary by provider and operation; check the keys exported by your installed snapshot before configuring filters. | Attribute | Description | |-----------|-------------| -| `llm.provider` | Wrapper-specific provider label: `google`, `azure`, `ollama` or `ibm` (Watsonx) | +| `llm.provider` | Wrapper-specific provider label: `google`, `ollama` or `ibm` (Watsonx) | | `llm.request.model` | Model name from the request | | `llm.response.model` | Model name from the response (if different) | | `llm.token_count.prompt` | Input token count | | `llm.token_count.completion` | Output token count | | `llm.token_count.total` | Total token count | | `input.value` / `output.value` | Plain text input/output | -| `fi.raw_input` / `fi.raw_output` | Full request/response as JSON | +| `fi.raw_input` / `fi.raw_output` | Best-effort serialized request/response; not guaranteed to contain complete JSON |