HYBIM-948 refresh README and changelog for first Splunk AO release - #195
HYBIM-948 refresh README and changelog for first Splunk AO release#195pradystar wants to merge 1 commit into
Conversation
fercor-cisco
left a comment
fercor-cisco
left a comment
There was a problem hiding this comment.
🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.
Verdict: request_changes — The new "Export diagnostics" docs describe a public attribute (processor.export_health) and rejection/recovery/logger behavior that do not exist in the source.
| The processor returned by `add_splunk_ao_span_processor()` exposes the latest | ||
| receiver acknowledgement as `processor.export_health`. Its `healthy` value is: | ||
|
|
||
| - `None` before an acknowledgement, or after a transport or non-2xx failure. | ||
| - `True` after an accepted 2xx response. | ||
| - `False` after a 2xx response that rejects telemetry. | ||
|
|
||
| This is advisory diagnostic state, not a delivery guarantee. |
There was a problem hiding this comment.
🟠 major (documentation): processor.export_health does not exist. A repo-wide grep for export_health matches only this README line — nothing in src/ or tests/. The object returned by add_splunk_ao_span_processor() is a SplunkAOSpanProcessor (src/splunk_ao/otel.py:155), whose only public members are on_start, on_end, shutdown, force_flush, and the exporter/processor properties. A user who follows these docs and reads processor.export_health.healthy will get an AttributeError, and the entire None/True/False semantics described here are fabricated. Either implement the attribute or remove this block.
🤖 Generated by the Astra agent
| A successful HTTP response can still acknowledge that some or all spans were | ||
| rejected. The SDK emits a sanitized, rate-limited error for those | ||
| acknowledgements and one informational message after recovery. Export failures | ||
| never fail the instrumented application or business request. |
There was a problem hiding this comment.
🟠 major (documentation): This claims the SDK detects successful-HTTP-response telemetry rejections and "emits a sanitized, rate-limited error for those acknowledgements and one informational message after recovery." No such logic exists in the export path: NormalizingSpanExporter.export() (src/splunk_ao/exporter/span_transform.py:84) simply delegates to the underlying OTLP exporter, and none of the exporter modules parse partial-success responses or emit logs. Please remove or correct this paragraph.
🤖 Generated by the Astra agent
|
|
||
| logging.basicConfig(level=logging.INFO) | ||
| logging.getLogger("opentelemetry.exporter.otlp.proto.http.trace_exporter").setLevel(logging.WARNING) | ||
| logging.getLogger("splunk_ao.exporter").setLevel(logging.INFO) |
There was a problem hiding this comment.
🟠 major (documentation): There is no splunk_ao.exporter logger that surfaces "Agent Observability successful-response rejection diagnostics." The exporter modules (sink.py, o11y.py, standalone.py, config.py, span_transform.py) contain no logging.getLogger / log calls at all. Setting this logger to INFO will produce nothing. The opentelemetry.exporter.otlp... line above it (transport/auth/retry/HTTP errors) is accurate; this line is not.
🤖 Generated by the Astra agent
| - Successful HTTP responses that reject telemetry produce sanitized, | ||
| rate-limited SDK error logs and a recovery log after a later accepted | ||
| response. | ||
| - Exporters expose bounded, read-only receiver-acknowledgement health. Health is | ||
| unknown before an acknowledgement and after ordinary transport or non-2xx | ||
| failures; it is not a delivery guarantee. |
There was a problem hiding this comment.
🟠 major (documentation): These two Diagnostics bullets describe the same non-existent behavior flagged in README: (1) SDK-emitted sanitized/rate-limited rejection errors with a recovery log, and (2) exporters exposing "read-only receiver-acknowledgement health" (i.e. export_health). Neither exists in the source. Remove or align with what the code actually does once the README section is corrected.
🤖 Generated by the Astra agent
2 participants
Summary
Refresh the README and changelog for the first Splunk AO Python SDK release, covering standalone and O11y configuration and the SDK’s OTLP based telemetry behavior.
Why
The existing documentation described legacy Galileo behavior and did not accurately explain current routing, lifecycle, batching, authentication, diagnostics, and OpenTelemetry integration requirements.
What changed
@log, handler, manual logger,flush(),terminate(), and provider shutdown behavior.Tests
Validated 23 Python examples, 9 shell examples, 76 focused tests.