{"id":50996754,"url":"https://github.com/umit/opentelemetry-java-instrumentation-open-ai","last_synced_at":"2026-06-20T10:32:22.266Z","repository":{"id":364148937,"uuid":"1266618030","full_name":"umit/opentelemetry-java-instrumentation-open-ai","owner":"umit","description":"OpenTelemetry Java agent extension for OpenAI Java SDK 4.x GenAI telemetry","archived":false,"fork":false,"pushed_at":"2026-06-11T20:09:59.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T22:04:11.901Z","etag":null,"topics":["genai","instrumentation","java","javaagent","observability","openai","opentelemetry"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T19:43:46.000Z","updated_at":"2026-06-11T20:04:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/umit/opentelemetry-java-instrumentation-open-ai","commit_stats":null,"previous_names":["umit/opentelemetry-java-instrumentation-open-ai"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/umit/opentelemetry-java-instrumentation-open-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umit%2Fopentelemetry-java-instrumentation-open-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umit%2Fopentelemetry-java-instrumentation-open-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umit%2Fopentelemetry-java-instrumentation-open-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umit%2Fopentelemetry-java-instrumentation-open-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umit","download_url":"https://codeload.github.com/umit/opentelemetry-java-instrumentation-open-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umit%2Fopentelemetry-java-instrumentation-open-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34566920,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-20T02:00:06.407Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["genai","instrumentation","java","javaagent","observability","openai","opentelemetry"],"created_at":"2026-06-20T10:32:21.739Z","updated_at":"2026-06-20T10:32:22.257Z","avatar_url":"https://github.com/umit.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenTelemetry Java Instrumentation for OpenAI\n\n[![CI](https://github.com/umit/opentelemetry-java-instrumentation-open-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/umit/opentelemetry-java-instrumentation-open-ai/actions/workflows/ci.yml)\n\nOpenTelemetry Java agent extension for instrumenting the OpenAI Java SDK 4.x.\n\nThe project follows the OpenTelemetry Java instrumentation split:\n\n- `io.github.umitunal.opentelemetry.javaagent.instrumentation.openai.v4_0`: Java agent module and Byte Buddy advice.\n- `io.github.umitunal.opentelemetry.instrumentation.openai.v4_0`: reusable telemetry helpers and proxy wrappers.\n\n## Requirements\n\n- Java 17 or later\n- Maven 3.9 or later\n- OpenTelemetry Java agent 2.28.1 or later\n- OpenAI Java SDK 4.x\n\n## What It Instruments\n\n- `OpenAIOkHttpClient.Builder.build()` is wrapped automatically by the Java agent extension.\n- `OpenAIClient.chat().completions().create(...)`\n- `OpenAIClient.chat().completions().createStreaming(...)`\n- `OpenAIClient.async().chat().completions().create(...)`\n\nThe instrumentation emits GenAI client spans, token usage metrics, operation duration metrics, streaming latency metrics, and optional prompt/output/tool content.\n\nTelemetry follows the OpenTelemetry GenAI semantic conventions:\n\n```text\nhttps://opentelemetry.io/docs/specs/semconv/gen-ai/\n```\n\n## Build And Test\n\n```bash\nmvn -q test\nmvn -q package\n```\n\nThe extension jar is produced at:\n\n```text\ntarget/opentelemetry-java-instrumentation-open-ai-0.2.0.jar\n```\n\n## Installation\n\nDownload the OpenTelemetry Java agent from the official releases page:\n\n```text\nhttps://github.com/open-telemetry/opentelemetry-java-instrumentation/releases\n```\n\nBuild this extension locally:\n\n```bash\nmvn -q package\n```\n\nThen attach both the OpenTelemetry Java agent and this extension:\n\n```bash\njava \\\n  -javaagent:/path/to/opentelemetry-javaagent.jar \\\n  -Dotel.javaagent.extensions=/path/to/opentelemetry-java-instrumentation-open-ai-0.2.0.jar \\\n  -Dotel.instrumentation.openai-java.enabled=false \\\n  -Dotel.instrumentation.openai.content.capture.mode=event \\\n  -jar app.jar\n```\n\n`otel.instrumentation.openai-java.enabled=false` avoids double instrumentation when the upstream OpenAI Java instrumentation is also present in the Java agent.\n\n## Content Capture\n\nContent capture is disabled by default:\n\n```text\notel.instrumentation.openai.content.capture.mode=off\n```\n\nSupported modes:\n\n- `off`: do not capture prompts, outputs, or tool definitions.\n- `event`: emit the OpenTelemetry GenAI event `gen_ai.client.inference.operation.details`.\n- `span_attribute`: attach content fields directly to the chat span for Jaeger/Grafana debugging.\n- `both`: emit the GenAI event and span attributes.\n\nThe standard OpenTelemetry GenAI model defines `gen_ai.input.messages`, `gen_ai.output.messages`, and `gen_ai.tool.definitions` as opt-in attributes on the `gen_ai.client.inference.operation.details` event. The `span_attribute` mode is a backend compatibility/debug mode, not the strict GenAI event model.\n\nContent capture can include prompts, outputs, tool arguments, and tool results. Enable it only in environments where collecting this data is acceptable.\n\n## Emitted Telemetry\n\n- Span: `chat {gen_ai.request.model}` with `gen_ai.operation.name=chat` and `gen_ai.provider.name=openai`.\n- Metrics: `gen_ai.client.token.usage`, `gen_ai.client.operation.duration`, `gen_ai.client.operation.time_to_first_chunk`, and `gen_ai.client.operation.time_per_output_chunk`.\n- OpenAI attributes include `openai.api.type`, `openai.request.service_tier`, `openai.response.service_tier`, and `openai.response.system_fingerprint` when available.\n\n## Example Trace\n\nA chat completion with tool calling creates a client span similar to:\n\n```text\nchat gpt-4o-mini\n|-- gen_ai.operation.name = chat\n|-- gen_ai.provider.name = openai\n|-- gen_ai.request.model = gpt-4o-mini\n|-- gen_ai.request.max_tokens = 256\n|-- gen_ai.request.temperature = 0.2\n|-- gen_ai.request.top_p = 1\n|-- gen_ai.response.id = chatcmpl_...\n|-- gen_ai.response.model = gpt-4o-mini\n|-- gen_ai.response.finish_reasons = [\"tool_calls\"]\n|-- gen_ai.usage.cache_read.input_tokens = 256\n|-- gen_ai.usage.input_tokens = 349\n|-- gen_ai.usage.output_tokens = 47\n|-- openai.api.type = chat_completions\n`-- openai.response.system_fingerprint = fp_...\n```\n\nWhen content capture is enabled with `event`, the span also contains an opt-in event with request, response, and tool content:\n\n```text\nevent: gen_ai.client.inference.operation.details\n|-- gen_ai.input.messages = [\n|     {\n|       \"role\": \"system\",\n|       \"content\": \"You fetch http.cat images for HTTP status codes. Use the get_http_cat tool, then summarize the result for the user.\"\n|     },\n|     {\n|       \"role\": \"user\",\n|       \"content\": \"Show me the cat for HTTP 404\"\n|     }\n|   ]\n|-- gen_ai.output.messages = [\n|     {\n|       \"role\": \"assistant\",\n|       \"content\": \"\",\n|       \"tool_calls\": [\n|         {\n|           \"id\": \"call_...\",\n|           \"type\": \"function\",\n|           \"function\": {\n|             \"name\": \"get_http_cat\",\n|             \"arguments\": \"{\\\"status_code\\\": 404}\"\n|           }\n|         }\n|       ]\n|     }\n|   ]\n`-- gen_ai.tool.definitions = [\n      {\n        \"type\": \"function\",\n        \"function\": {\n          \"name\": \"get_http_cat\",\n          \"description\": \"Fetch the http.cat image metadata for an HTTP status code.\",\n          \"parameters\": {\n            \"type\": \"object\",\n            \"required\": [\"status_code\"],\n            \"additionalProperties\": false,\n            \"properties\": {\n              \"status_code\": {\n                \"type\": \"integer\",\n                \"description\": \"The HTTP status code to look up, e.g. 200, 404, 500.\"\n              }\n            }\n          }\n        }\n      }\n    ]\n```\n\nWhen content capture is enabled with `span_attribute`, the same content fields are attached directly to the chat span for backend compatibility and debugging.\n\n## Notes\n\n- Production code avoids a compile-time dependency on the OpenAI SDK and uses reflection/proxy wrapping.\n- Test fixtures under `src/test/java/com/openai/client` are minimal SDK shims used only by unit tests.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumit%2Fopentelemetry-java-instrumentation-open-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumit%2Fopentelemetry-java-instrumentation-open-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumit%2Fopentelemetry-java-instrumentation-open-ai/lists"}