From 1b6f8d6b98e387dbb16ed7186a4da9ce9b78bab9 Mon Sep 17 00:00:00 2001 From: etserend Date: Fri, 7 Aug 2026 14:15:38 -0500 Subject: [PATCH 1/5] fix(docs): correct stale flush() docstrings to reflect drain-only semantics (HYBIM-966) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit flush() and async_flush() no longer upload traces — they only drain the OTLP export queue since PR #155. Update singleton.py and decorator.py docstrings to match the actual behavior. Co-Authored-By: Claude Opus 4.7 --- src/splunk_ao/decorator.py | 5 +++-- src/splunk_ao/utils/singleton.py | 10 +++++----- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/src/splunk_ao/decorator.py b/src/splunk_ao/decorator.py index fb02472b..4513b198 100644 --- a/src/splunk_ao/decorator.py +++ b/src/splunk_ao/decorator.py @@ -1349,9 +1349,10 @@ def _on_flush_error(exc: Exception) -> None: def flush_all(self) -> None: """ - Upload all captured traces under all contexts to Splunk AO. + Drain the OTLP export queue for all active logger contexts. - This method flushes all traces regardless of project or log stream. + This method drains all loggers regardless of project or agent stream. + It does not conclude open spans or upload traces directly. """ SplunkAOLoggerSingleton().flush_all() diff --git a/src/splunk_ao/utils/singleton.py b/src/splunk_ao/utils/singleton.py index 99c00017..97c9bb51 100644 --- a/src/splunk_ao/utils/singleton.py +++ b/src/splunk_ao/utils/singleton.py @@ -295,11 +295,11 @@ def flush( agent_stream_id: str | None = None, ) -> None: """ - Flush (upload and clear) a SplunkAOLogger instance. + Drain the OTLP export queue for a SplunkAOLogger instance. - If both project and agent_stream are None, then all cached loggers are flushed - and cleared. Otherwise, only the specific logger corresponding to the provided - key (project, agent_stream) is flushed and removed. + If both project and agent_stream are None, then all cached loggers are drained. + Otherwise, only the specific logger corresponding to the provided + key (project, agent_stream) is drained. Parameters ---------- @@ -331,7 +331,7 @@ def flush( self._splunk_ao_loggers[key].flush() def flush_all(self) -> None: - """Flush (upload and clear) all SplunkAOLogger instances.""" + """Drain the OTLP export queue for all SplunkAOLogger instances.""" with self._lock: # Terminate and clear all logger instances. for logger in self._splunk_ao_loggers.values(): From 162d9eefc966ed47d83048ffd47e7428003d31f8 Mon Sep 17 00:00:00 2001 From: etserend Date: Fri, 7 Aug 2026 17:06:13 -0500 Subject: [PATCH 2/5] fix(docs): correct stale flush() docstring in SplunkAODecorator (HYBIM-966) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit flush() no longer uploads traces — it only drains the OTLP export queue. Also note it does not conclude open spans, matching the CHANGELOG entry from PR #155. Co-Authored-By: Claude Opus 4.7 --- src/splunk_ao/decorator.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/splunk_ao/decorator.py b/src/splunk_ao/decorator.py index 4513b198..6cf77952 100644 --- a/src/splunk_ao/decorator.py +++ b/src/splunk_ao/decorator.py @@ -1309,9 +1309,10 @@ def flush( on_error: Callable[[Exception], None] | None = None, ) -> None: """ - Upload all captured traces under a project and agent stream context to Splunk AO. + Drain the OTLP export queue for a specific project and agent stream context. - If no project or agent stream is provided, then the currently initialized context is used. + Does not conclude open spans or upload traces directly. If no project or + agent stream is provided, the currently initialized context is used. Parameters ---------- From 834f543d1dd5db8fb4902fc6df5addac5c6f7a98 Mon Sep 17 00:00:00 2001 From: etserend Date: Fri, 7 Aug 2026 17:32:46 -0500 Subject: [PATCH 3/5] fix(examples): update flush() comments to reflect drain-only semantics (HYBIM-966) Replace stale "send the trace to Splunk AO" / "uploads traces" inline comments with "drain the OTLP export queue" across chatbot examples, redaction example, and migration-tool before/after examples. Co-Authored-By: Claude Opus 4.7 --- examples/chatbot/sample-project-chatbot/anthropic/app.py | 2 +- .../chatbot/sample-project-chatbot/azure-inference/app.py | 2 +- examples/chatbot/sample-project-chatbot/openai-ollama/app.py | 2 +- .../logging-samples/splunk-ao-logger/redaction-example.py | 4 ++-- splunk-ao-migration-tool/examples/after_splunk_ao.py | 2 +- splunk-ao-migration-tool/examples/before_galileo.py | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/examples/chatbot/sample-project-chatbot/anthropic/app.py b/examples/chatbot/sample-project-chatbot/anthropic/app.py index 0b5b7128..f416354a 100644 --- a/examples/chatbot/sample-project-chatbot/anthropic/app.py +++ b/examples/chatbot/sample-project-chatbot/anthropic/app.py @@ -11,7 +11,7 @@ as a workflow span - The call to the LLM is logged manually as an LLM span. - After the response is received, the trace is concluded with the response - and flushed to ensure it is sent to Splunk AO. + and the export queue is drained. To run this, you will need to have the following environment variables set: - `SPLUNK_AO_API_KEY`: Your Splunk AO API key. diff --git a/examples/chatbot/sample-project-chatbot/azure-inference/app.py b/examples/chatbot/sample-project-chatbot/azure-inference/app.py index dcf9f903..edb93d79 100644 --- a/examples/chatbot/sample-project-chatbot/azure-inference/app.py +++ b/examples/chatbot/sample-project-chatbot/azure-inference/app.py @@ -11,7 +11,7 @@ as a workflow span - The call to the LLM is logged manually as an LLM span. - After the response is received, the trace is concluded with the response - and flushed to ensure it is sent to Splunk AO. + and the export queue is drained. To run this, you will need to have the following environment variables set: - `SPLUNK_AO_API_KEY`: Your Splunk AO API key. diff --git a/examples/chatbot/sample-project-chatbot/openai-ollama/app.py b/examples/chatbot/sample-project-chatbot/openai-ollama/app.py index 9b6fa658..a35ef28a 100644 --- a/examples/chatbot/sample-project-chatbot/openai-ollama/app.py +++ b/examples/chatbot/sample-project-chatbot/openai-ollama/app.py @@ -12,7 +12,7 @@ - The call to the LLM is logged as an LLM span using the Splunk AO OpenAI integration which logs the span automatically. - After the response is received, the trace is concluded with the response - and flushed to ensure it is sent to Splunk AO. + and the export queue is drained. To run this, you will need to have the following environment variables set: - `SPLUNK_AO_API_KEY`: Your Splunk AO API key. diff --git a/examples/logging-samples/splunk-ao-logger/redaction-example.py b/examples/logging-samples/splunk-ao-logger/redaction-example.py index 3768bad8..d4f3e1da 100644 --- a/examples/logging-samples/splunk-ao-logger/redaction-example.py +++ b/examples/logging-samples/splunk-ao-logger/redaction-example.py @@ -19,7 +19,7 @@ redacted_input = user_input.replace(sensitive_info, "***") trace = logger.start_trace(input=user_input, redacted_input=redacted_input) -logger.flush() # send the trace to Splunk AO +logger.flush() # drain the OTLP export queue # Example of how to create "redacted_input", matching email as sensitive info # --------------------------------------------------------------------------- @@ -37,7 +37,7 @@ else: trace = logger.start_trace(input=user_input) -logger.flush() # send the trace to Splunk AO +logger.flush() # drain the OTLP export queue # It's also possible to use a service such as https://www.private-ai.com/ to create the redacted_input diff --git a/splunk-ao-migration-tool/examples/after_splunk_ao.py b/splunk-ao-migration-tool/examples/after_splunk_ao.py index 6ee59db7..e3508ae6 100644 --- a/splunk-ao-migration-tool/examples/after_splunk_ao.py +++ b/splunk-ao-migration-tool/examples/after_splunk_ao.py @@ -21,4 +21,4 @@ def call_llm(prompt: str) -> str: logger.start_session(name="my-session") logger.add_llm_span(input="Hello", output="Hi", model="gpt-4") logger.conclude() # closes current span; no flush kwarg -logger.flush() # uploads traces +logger.flush() # drain the OTLP export queue diff --git a/splunk-ao-migration-tool/examples/before_galileo.py b/splunk-ao-migration-tool/examples/before_galileo.py index 7f7c1433..c8c0eb7e 100644 --- a/splunk-ao-migration-tool/examples/before_galileo.py +++ b/splunk-ao-migration-tool/examples/before_galileo.py @@ -21,4 +21,4 @@ def call_llm(prompt: str) -> str: logger.start_session(name="my-session") logger.add_llm_span(input="Hello", output="Hi", model="gpt-4") logger.conclude() # closes current span; no flush kwarg -logger.flush() # uploads traces +logger.flush() # drain the OTLP export queue From 0993b0e6a3cf094bbff14650e70eee333eb3f6d5 Mon Sep 17 00:00:00 2001 From: etserend Date: Mon, 10 Aug 2026 12:19:39 -0500 Subject: [PATCH 4/5] fix(examples): update flush() comment in basic/metadata logging examples (HYBIM-966) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace "Flush the trace to Splunk AO" → "Drain the OTLP export queue" in basic-example.py and metadata-example.py. Co-Authored-By: Claude Opus 4.7 --- examples/logging-samples/splunk-ao-logger/basic-example.py | 2 +- examples/logging-samples/splunk-ao-logger/metadata-example.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/logging-samples/splunk-ao-logger/basic-example.py b/examples/logging-samples/splunk-ao-logger/basic-example.py index d5c53d43..0d48dd4d 100644 --- a/examples/logging-samples/splunk-ao-logger/basic-example.py +++ b/examples/logging-samples/splunk-ao-logger/basic-example.py @@ -29,7 +29,7 @@ # Conclude the trace with the final output logger.conclude(output="Hello, this is a test", duration_ns=1000) -# Flush the trace to Splunk AO +# Drain the OTLP export queue logger.flush() diff --git a/examples/logging-samples/splunk-ao-logger/metadata-example.py b/examples/logging-samples/splunk-ao-logger/metadata-example.py index 16483e22..f9407512 100644 --- a/examples/logging-samples/splunk-ao-logger/metadata-example.py +++ b/examples/logging-samples/splunk-ao-logger/metadata-example.py @@ -27,7 +27,7 @@ # Conclude the trace with the final output logger.conclude(output_answer) -# Flush the trace to Splunk AO +# Drain the OTLP export queue logger.flush() # Show link to Splunk AO log stream From 00a24998762f928ffbe58444478a53dadcfb460e Mon Sep 17 00:00:00 2001 From: etserend Date: Mon, 10 Aug 2026 12:23:50 -0500 Subject: [PATCH 5/5] fix(examples): remove logger.flush() from simple SDK examples (HYBIM-966) flush() is no longer needed after conclude() in basic single-trace examples. Remove it from the class docstring, logging samples, chatbot basic examples, and README code blocks. Also fix stale "uploads traces" comment in migration tool README. Co-Authored-By: Claude Opus 4.7 --- examples/chatbot/basic-examples/README.md | 3 --- examples/chatbot/basic-examples/hallucination.py | 3 --- examples/chatbot/basic-examples/test.py | 3 --- examples/logging-samples/splunk-ao-logger/basic-example.py | 3 --- examples/logging-samples/splunk-ao-logger/metadata-example.py | 3 --- .../logging-samples/splunk-ao-logger/retriever-example.py | 3 --- splunk-ao-migration-tool/README.md | 4 ++-- src/splunk_ao/logger/logger.py | 1 - 8 files changed, 2 insertions(+), 21 deletions(-) diff --git a/examples/chatbot/basic-examples/README.md b/examples/chatbot/basic-examples/README.md index d9b6eacf..11c48d25 100644 --- a/examples/chatbot/basic-examples/README.md +++ b/examples/chatbot/basic-examples/README.md @@ -63,9 +63,6 @@ logger.add_llm_span( # Conclude the trace logger.conclude(output=response.choices[0].message.content.strip()) - -# Flush the traces to Splunk AO -logger.flush() ``` This approach gives you more control over what gets logged and when, allowing you to: diff --git a/examples/chatbot/basic-examples/hallucination.py b/examples/chatbot/basic-examples/hallucination.py index d781114f..06007215 100644 --- a/examples/chatbot/basic-examples/hallucination.py +++ b/examples/chatbot/basic-examples/hallucination.py @@ -101,6 +101,3 @@ def run_hallucination_demo(): # Run the main demonstration results = run_hallucination_demo() - - # Flush the traces to Splunk AO - logger.flush() diff --git a/examples/chatbot/basic-examples/test.py b/examples/chatbot/basic-examples/test.py index a0b40457..039b5ad6 100644 --- a/examples/chatbot/basic-examples/test.py +++ b/examples/chatbot/basic-examples/test.py @@ -54,8 +54,5 @@ # Conclude the trace logger.conclude(output=response_content) -# Flush the traces to Splunk AO -logger.flush() - # Print the response print(response_content) diff --git a/examples/logging-samples/splunk-ao-logger/basic-example.py b/examples/logging-samples/splunk-ao-logger/basic-example.py index 0d48dd4d..4b52a487 100644 --- a/examples/logging-samples/splunk-ao-logger/basic-example.py +++ b/examples/logging-samples/splunk-ao-logger/basic-example.py @@ -29,9 +29,6 @@ # Conclude the trace with the final output logger.conclude(output="Hello, this is a test", duration_ns=1000) -# Drain the OTLP export queue -logger.flush() - # Show link to Splunk AO log stream config = SplunkAOConfig.get() diff --git a/examples/logging-samples/splunk-ao-logger/metadata-example.py b/examples/logging-samples/splunk-ao-logger/metadata-example.py index f9407512..0a4a6186 100644 --- a/examples/logging-samples/splunk-ao-logger/metadata-example.py +++ b/examples/logging-samples/splunk-ao-logger/metadata-example.py @@ -27,9 +27,6 @@ # Conclude the trace with the final output logger.conclude(output_answer) -# Drain the OTLP export queue -logger.flush() - # Show link to Splunk AO log stream config = SplunkAOConfig.get() project_url = f"{config.console_url}project/{logger.project_id}" diff --git a/examples/logging-samples/splunk-ao-logger/retriever-example.py b/examples/logging-samples/splunk-ao-logger/retriever-example.py index 68032ad5..5b1b5333 100644 --- a/examples/logging-samples/splunk-ao-logger/retriever-example.py +++ b/examples/logging-samples/splunk-ao-logger/retriever-example.py @@ -55,9 +55,6 @@ logger.conclude(output="This is another trace conclude", duration_ns=1000) - # Flush the traces to splunk_ao - logger.flush() - # Show link to Splunk AO log stream config = SplunkAOConfig.get() diff --git a/splunk-ao-migration-tool/README.md b/splunk-ao-migration-tool/README.md index 250c0f95..6b97c7f5 100644 --- a/splunk-ao-migration-tool/README.md +++ b/splunk-ao-migration-tool/README.md @@ -391,7 +391,7 @@ logger = GalileoLogger(project="my-project", log_stream="production") logger.start_session(name="my-session") logger.add_llm_span(input="Hello", output="Hi", model="gpt-4") logger.conclude() # closes current span; no flush kwarg -logger.flush() # uploads traces +logger.flush() # drain the OTLP export queue ``` ### After (splunk-ao) @@ -418,7 +418,7 @@ logger = SplunkAOLogger(project="my-project", agent_stream="production") logger.start_session(name="my-session") logger.add_llm_span(input="Hello", output="Hi", model="gpt-4") logger.conclude() # closes current span; no flush kwarg -logger.flush() # uploads traces +logger.flush() # drain the OTLP export queue ``` --- diff --git a/src/splunk_ao/logger/logger.py b/src/splunk_ao/logger/logger.py index 8ebd8937..f7213c3b 100644 --- a/src/splunk_ao/logger/logger.py +++ b/src/splunk_ao/logger/logger.py @@ -208,7 +208,6 @@ class SplunkAOLogger(TracesLogger): duration_ns=1000 ) logger.conclude(output="I am!", duration_ns=2000) - logger.flush() ``` """