fix(docs): correct stale flush() docstrings to reflect drain-only semantics (HYBIM-966)

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:

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()

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)

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.

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.

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.

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)
 
-# Flush the trace to Splunk AO
-logger.flush()
-
 
 # Show link to Splunk AO log stream
 config = SplunkAOConfig.get()

examples/logging-samples/splunk-ao-logger/metadata-example.py

@@ -27,9 +27,6 @@
 # Conclude the trace with the final output
 logger.conclude(output_answer)
 
-# Flush the trace to Splunk AO
-logger.flush()
-
 # Show link to Splunk AO log stream
 config = SplunkAOConfig.get()
 project_url = f"{config.console_url}project/{logger.project_id}"

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
 

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()

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
 ```
 
 ---

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

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

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
         ----------
@@ -1349,9 +1350,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()
 

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()
     ```
     """
 

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():