Skip to content

feat(observability): add observability core module, TelemetryHook SPI and facade wiring - #1

Closed
khunj wants to merge 410 commits into
mainfrom
feature/observability-core
Closed

khunj wants to merge 410 commits into
mainfrom
feature/observability-core

Conversation

@khunj

@khunj khunj commented Oct 21, 2026

Copy link
Copy Markdown
Owner

概述

按设计文档 docs/superpowers/specs/2026-10-20-observability-java-port-design.md 落地 A2A-T Java SDK 可观测性(Plan A:核心模块 + SPI + 门面接线;Python SDK 可观测模块的 Java 移植)。协议层装饰器(Plan B)另行提交。

交付物

  • a2a-t-observability(新模块):A2ATObservabilityConfig(显式>.env>env>默认)、ObservabilitySetup(OTel 三信号自动装配:OTLP gRPC/HTTP + Console 降级,幂等)、A2ATSpan/CurrentSpans 手动 API、TracePropagation(W3C traceparent)、PayloadExtractor/Sanitizer(先脱敏后截断)、ObservabilityLLMClient(gen_ai.client.token.usage + ThreadLocal stash)、NegotiationMetrics(a2at.negotiation.total_rounds)、ObservabilityLogs(JSON 行,SLF4J + OTel Logger 双通道)、内置 Console 导出器(本地无 opentelemetry-exporter-logging)
  • a2a-t-observability-a2a(新模块骨架):协议层装饰器模块占位,Plan B 填充
  • a2a-t-core:TelemetryHook/TelemetryOperation SPI(NO_OP 默认,观测永不破坏业务流)
  • a2a-t-client / a2a-t-server:二级构造器注入 @nullable TelemetryHook,45 个公开方法包装为 a2at.sdk.{role}.{method} Span;continueNegotiation 终态上报协商轮次(AGREED→accept / REJECTED→reject)
  • env.example:可观测性 14 键配置小节

关键设计决策

  • OTel 1.64.0:api 编译依赖 + sdk/exporter ;getOrNoop() 防 GlobalOpenTelemetry.get() 副作用毒化全局
  • 依赖方向单向:observability→core/llm;a2a-java 1.1.0.Final 版本钉在 a2a 模块 pom(避免根 dependencyManagement 破坏 sample 传递解析)
  • 全部 hook 回调 try/catch 防护 + WARN;业务异常原样抛出

质量

  • 9 模块全量回归通过(a2a-t-sample/corpus 除外:sample 存在先于本分支的 AgentCard 编译错误,与本 PR 无关)
  • 逐任务审查 + 终审 + 修复波复审;遗留 follow-up 已记录于计划文档 Plan B 小节
  • 测试:观测模块 34 个新测试 + 门面 8 个新测试;命名注册表与 spec §5 逐字一致(与 a2a-java 仪表盘查询零改动兼容)

cnafan and others added 30 commits August 22, 2026 17:35
Signed-off-by: gcw_mr3RVhmf <cnafan@outlook.com>
Upstream renamed validateAndFillingTaskData to
validateTaskPromptAndDataFilling; the sample executor, strategy javadoc,
scenario loader javadoc and diagnosis service references now use the new
name.

Signed-off-by: ZhouJie6 <ivo.zhou@huawei.com>
…n-sample

feat(sample): add negotiation end-to-end demo and fromData/fromText API samples
Signed-off-by: gcw_mr3RVhmf <cnafan@outlook.com>
…ngle-brace

fix(prompt): keep single-brace example text verbatim instead of failing as unknown slot
Signed-off-by: gcw_mr3RVhmf <cnafan@outlook.com>
…parameters and drop CI e2e job

Split the server-side notificationDataFormat string parameter in the service-recovery sample schema into the 10 individual business fields defined by the template (7 required + 3 optional), update the required list and slot names accordingly, and align the sample inputs with the new parameter names. Remove the e2e-samples-unified job from CI.

Signed-off-by: wangruiyang8 <wangruiyang8@huawei.com>
Signed-off-by: qinyanhao01 <qinyanhao1@huawei.com>

# Conflicts:
#	a2a-t-sample/README.zh-CN.md
Signed-off-by: gcw_mr3RVhmf <cnafan@outlook.com>
* origin/main:
  fix(sample): adapt to validateTaskPromptAndDataFilling rename
  feat(sample): stream transport support and release-grade design document
  fix(client): use double-braced unknown slot to trigger render failure in tests
  fix(prompt): keep single-brace example text verbatim instead of failing as unknown slot
  refactor(sample): keep only generic rules in negotiation code, move all scenario values to scenario.json
  refactor(sample): load negotiation scenario data from scenario.json
  feat(sample): add negotiation end-to-end demo and fromData/fromText API samples
  fix(client): use double-braced unknown slot to trigger render failure in tests
  fix(prompt): keep single-brace example text verbatim instead of failing as unknown slot

Signed-off-by: gcw_mr3RVhmf <cnafan@outlook.com>

# Conflicts:
#	a2a-t-sample/README.zh-CN.md
#	a2a-t-sample/pom.xml
Signed-off-by: gcw_mr3RVhmf <cnafan@outlook.com>
…egotiation-evaluation

feat(sample): add private-line negotiation sample
Signed-off-by: qinyanhao01 <qinyanhao1@huawei.com>
…istency

Add service-recovery-client.javaargs.txt and service-recovery-server.javaargs.txt
to the pom, matching the pattern used by negotiation and other samples.
Document the new startup method in README.zh-CN.md.

Also fix the validateAndFillingNotificationData rename to
validateNotificationPromptAndDataFilling that broke service-recovery
compilation.

Signed-off-by: wangruiyang8 <wangruiyang8@huawei.com>
feat(sample): add service-recovery sample with unified SampleRunner
feat(sample):add task-t client env template
Signed-off-by: qinyanhao01 <qinyanhao1@huawei.com>
Signed-off-by: qinyanhao01 <qinyanhao1@huawei.com>

# Conflicts:
#	a2a-t-sample/pom.xml
…playable JSON report

Adds NegotiationEvalApp, a pure-Java evaluation entry under the negotiation
sample that drives the negotiation prompt interfaces in message order for
every case of the bundled eval-suite.json:

1. Task-T generation (generateTaskPromptFromDataWithSchema / fromText)
2. server validation with missing-slot detection
   (validateTaskPromptAndDataFilling)
3. Negotiation-T propose generation from the detected missing slots
   (generateNegotiationProposePromptFromData)
4. outbound propose validation (validateProposePromptAndDataFilling)
5. client fill + accept generation (generateNegotiationAcceptPromptFromData)
6. inbound accept validation with fill-value comparison
   (validateAcceptPromptAndDataFilling)
7. second Task-T validation deciding COMPLETED vs INPUT_REQUIRED

Every intermediate artifact (generated prompts, validation verdicts,
extracted parameters, per-slot errors, client fill values) is recorded per
case in a JSON report that is rewritten after each case, so a single case
can be replayed and audited without re-running it. The suite carries the
10 private-line-complaint cases (fromData/fromText channels, generation
fail-fast and value-constraint negatives) with expected outcomes; metrics
cover trigger accuracy, missing-slot exact match, propose outbound
validity, fill-value match and closed-loop completion.

Run: java @a2a-t-sample/target/eval.javaargs.txt [--case PLC-04]
[--out eval-report.json] /path/to/.env

Signed-off-by: ZhouJie6 <ivo.zhou@huawei.com>
…ctable

DefaultSemanticValidator.parseParams dropped parameters whose extracted
value was null, so FilledParamData did not even carry the key. A null
param is the semantic validator's explicit signal that a schema slot is
missing from the content (per the content_validation user prompt: slots
that cannot be extracted must be output as null). With the key gone, any
caller that detects missing parameters by scanning FilledParamData for
blank values cannot see the missing slot, and negotiation is silently
never triggered for it.

The parse now keeps null-valued keys (the normalized map is wrapped with
Collections.unmodifiableMap instead of Map.copyOf, which rejects null
values), and ValidationPipeline.mergeParams already carries them through
unchanged.

Found by the negotiation interface closed-loop evaluator (eval-suite case
PLC-10: the LLM returned 任务对象=null with semantic_verdict=true, the
missing slot vanished from FilledParamData, and the negotiation flow
never started).

Signed-off-by: ZhouJie6 <ivo.zhou@huawei.com>
… interface evaluator

- add a dedicated subsection explaining how the javaargs.txt files work
  (JDK 9+ @-argfile syntax, generated by the antrun plugin at package
  time, one file per entry point) so the run commands are readable
  without Maven knowledge; note the Windows -Dfile.encoding=UTF-8 hint
- document the eval entry: full-suite / --case replay / --out forms,
  incremental report writing, and where the eval suite lives
- list the evaluator in the code-structure tree and the coverage matrix

Signed-off-by: ZhouJie6 <ivo.zhou@huawei.com>
…n-interface-eval

feat(sample): negotiation interface closed-loop evaluator with replayable JSON report
…lidator-null-params

fix(prompt): preserve null semantic params so missing slots stay detectable
Relocate the negotiation session context record from the negotiation
content package to core.model so MetadataContent can reference it
without a reverse module dependency. The record is moved verbatim
(id/round/maxRounds with validation, DEFAULT_MAX_ROUNDS, of/nextRound/
isExhausted), its test mirrors the new package, and all imports and
fully-qualified references across core/negotiation/client/server/sample
are updated. The deprecated types.model.NegotiationContext demo class
and the negotiation package-structure pin are left in sync.

Signed-off-by: codetalks-hw <lihaizhen5@huawei.com>
Add an optional negotiationContext component to MetadataContent together
with the 3-arg convenience constructor delegating a null context, so
non-negotiation messages keep their two-key metadata shape. The
negotiation generation orchestrator now passes its context through, and
buildMetadataContent() returns Map<String,Object> carrying, for
negotiation messages only, a third negotiationContext key mapped to the
nested {id, round, maxRounds} object matching the A2A-T message shape.
Contract tests now pin three keys on the negotiation path and two keys
elsewhere.

Signed-off-by: codetalks-hw <lihaizhen5@huawei.com>
The four validate*PromptAndDataFilling methods on NegotiationContentService,
A2ATClient and A2ATServer now take the negotiation context as their second
argument, mirroring the from-text generation APIs, and the compliance checker
validates the passed context (UUID shape, round within budget) instead of
re-parsing a rendered context section. NegotiationRuleCheckResult shrinks to
(passed, errors), the rule-checker adapter becomes a per-call bridge carrying
the context, and a null context is reported as negotiation_invalid_input.

The private-line sample reads the context back from the negotiationContext
metadata entry through NegotiationMetadataReader.readContext and feeds it into
the validation calls, replacing the round trip through the rendered text.

Signed-off-by: codetalks-hw <lihaizhen5@huawei.com>
The negotiation session context now travels exclusively in the
negotiationContext metadata entry, so the rendered message no longer
carries a context section: all fourteen Negotiation-T templates drop
their leading context section, the seven generators stop injecting the
slot.context value, NegotiationContextRenderer and its dedicated tests
are deleted, the section.context/slot.context keys leave both
vocabulary files together with Vocabulary.CANONICAL_KEYS, the template
lint profiles and the negotiation-context rule are dropped, and the
semantic-validation system prompts lose the section.context slot entry
and the id example parameter.

The eighteen golden fixtures are regenerated (each losing exactly the
five context lines) and reviewed, the assertion suite now pins the
absence of the context section alongside the metadata context, and the
private-line evaluation corpus drops the hand-written context headers
from the client supplement and all one hundred completed prompts.

Signed-off-by: codetalks-hw <lihaizhen5@huawei.com>
The developer guides now describe the four-component MetadataContent with
the conditional negotiationContext metadata key carrying the nested
{id, round, maxRounds} object, the NegotiationContext home in the core
model package, the context-parameter signatures of the four
validate*PromptAndDataFilling methods, and the rule gate validating the
caller-supplied context instead of parsing a rendered section. The
end-to-end examples pass the context through and the method-count drift
(thirteen vs the actual fourteen facade methods) is corrected, as is the
same drift in the two facade symmetry tests that missed the abort
methods.

Signed-off-by: codetalks-hw <lihaizhen5@huawei.com>
…ationContext validate APIs

Signed-off-by: codetalks-hw <lihaizhen5@huawei.com>
zhangwenjun-huawei and others added 27 commits September 16, 2026 12:03
fix(resources): update ran-energy-saving template
* dev:
  Merge pull request project-openan#193 from zhangwenjun-huawei/dev
  fix(resources): update ran-energy-saving template
  Merge pull request project-openan#192 from zhangwenjun-huawei/dev
  feat(llm): add DEBUG-level LLM call logging with opt-in payload switch
  Merge pull request project-openan#190 from zhangwenjun-huawei/dev
  feat(corpus): add Negotiation-T accuracy verification module and unify suite directories
  Merge pull request project-openan#189 from mamusen-huawei/dev
  fix(resources): enable required slots in ran-energy-saving en-US slot.json
  style(corpus): normalize ran-energy-saving modify input case JSON to benchmark style
  test(corpus): add ran-energy-saving modify input cases with unified schema
  Merge pull request project-openan#187 from Zhoujie628/dev
  feat(llm): add configurable TLS verification
  Merge pull request project-openan#183 from zhangwenjun-huawei/dev
  feat(corpus): rewrite a2a-t-corpus as a data-driven accuracy verification module
  Merge pull request project-openan#182 from zhangwenjun-huawei/dev
  chore: add .gitattributes and normalize line endings to LF
  Merge pull request project-openan#181 from zhangwenjun-huawei/dev
  fix(ci): allow Terminology Explanation in Authorization-T lint profile
  ci: restrict push and pull_request triggers to main and dev branches
  fix(doc): refresh template.md and docs
Signed-off-by: zhangwenjun-huawei <zhangwenjun19@huawei.com>
Signed-off-by: zhangwenjun-huawei <zhangwenjun19@huawei.com>
chore(ci): exclude corpus module from release pipeli
@khunj

khunj commented Oct 21, 2026

Copy link
Copy Markdown
Owner Author

Created in error (wrong repo). The real PR is at https://github.com/project-openan/a2a-t-sdk-java — closing this one.

@khunj khunj closed this Oct 21, 2026
@khunj

khunj commented Oct 21, 2026

Copy link
Copy Markdown
Owner Author

Created in error (wrong repo). The real PR is at https://github.com/project-openan/a2a-t-sdk-java - closing this one.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants