fix: address PR review comments on auditable logging

- Add Cloud Run service name filter to audit log query examples
- Document possible values for LOG_LEVEL, LOG_FORMAT, AGENT_LOGGING_DETAIL in configmap
- Document LOG_FORMAT=text behavior in audit logging docs
- Add test assertions verifying audit fields (user_id, org_id, order_id, request_id) in log messages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: luis5tb

deploy/cloudrun/README.md

@@ -1324,23 +1324,27 @@ This provides a full data lineage audit trail: every piece of information disclo
 
 ### Querying Audit Logs
 
-Cloud Logging automatically parses JSON log fields. Example queries:
+Cloud Logging automatically parses JSON log fields. To filter logs from the Lightspeed Agent service specifically, add a `resource.labels.service_name` filter:
 
 ```bash
-# All actions by a specific user
-gcloud logging read 'jsonPayload.user_id="<user-id>"' \
+# All Lightspeed Agent logs (filter by Cloud Run service name)
+gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="lightspeed-agent"' \
+  --project=$GOOGLE_CLOUD_PROJECT --limit=50
+
+# All actions by a specific user (scoped to the agent service)
+gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="lightspeed-agent" AND jsonPayload.user_id="<user-id>"' \
   --project=$GOOGLE_CLOUD_PROJECT --limit=50
 
 # All events in a single request (correlation)
-gcloud logging read 'jsonPayload.request_id="<request-id>"' \
+gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="lightspeed-agent" AND jsonPayload.request_id="<request-id>"' \
   --project=$GOOGLE_CLOUD_PROJECT
 
 # All MCP data access for an organization
-gcloud logging read 'jsonPayload.org_id="<org-id>" AND jsonPayload.message=~"mcp_jwt_forwarded"' \
+gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="lightspeed-agent" AND jsonPayload.org_id="<org-id>" AND jsonPayload.message=~"mcp_jwt_forwarded"' \
   --project=$GOOGLE_CLOUD_PROJECT
 
 # All tool calls with data source tracking
-gcloud logging read 'jsonPayload.message=~"tool_call_completed"' \
+gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="lightspeed-agent" AND jsonPayload.message=~"tool_call_completed"' \
   --project=$GOOGLE_CLOUD_PROJECT --limit=20
 ```
 

deploy/podman/lightspeed-agent-configmap.yaml

@@ -74,8 +74,11 @@ data:
   SERVICE_CONTROL_ENABLED: "false"
 
   # Logging and Audit Trail
-  # LOG_FORMAT=json enables structured audit logging with user_id,
-  # org_id, order_id, and request_id in every log record.
+  # LOG_LEVEL: DEBUG, INFO, WARNING, ERROR
+  # LOG_FORMAT: "json" (structured with audit fields: user_id, org_id,
+  #   order_id, request_id) or "text" (human-readable, no audit fields)
+  # AGENT_LOGGING_DETAIL: "basic" (tool names and lifecycle events only)
+  #   or "detailed" (also includes tool arguments and truncated results)
   LOG_LEVEL: "DEBUG"
   LOG_FORMAT: "json"
   AGENT_LOGGING_DETAIL: "detailed"

docs/configuration.md

@@ -251,7 +251,12 @@ AGENT_LOGGING_DETAIL=detailed  # Include tool args/results in logs
 
 #### Audit Logging
 
-When `LOG_FORMAT=json` (the default), every log record automatically includes audit context fields:
+The `LOG_FORMAT` setting controls how log records are formatted:
+
+- **`json`** (default) — Structured JSON output. Every log record automatically includes audit context fields (`user_id`, `org_id`, `order_id`, `request_id`). Recommended for production and Cloud Run, where Cloud Logging parses these fields for querying.
+- **`text`** — Human-readable output (`timestamp - logger - level - message`). Audit context fields are **not** included in the log record. The agent execution plugin still embeds `user_id`, `org_id`, `order_id`, and `request_id` in the log message text, but they are not available as structured fields for filtering. Recommended for local development.
+
+When `LOG_FORMAT=json`, every log record automatically includes audit context fields:
 
 | Field | Source | Description |
 |-------|--------|-------------|

tests/test_logging_plugin.py

@@ -6,6 +6,12 @@
 import pytest
 
 from lightspeed_agent.api.a2a.logging_plugin import AgentLoggingPlugin, _truncate
+from lightspeed_agent.auth.middleware import (
+    _request_id,
+    _request_order_id,
+    _request_org_id,
+    _request_user_id,
+)
 
 
 class TestTruncate:
@@ -331,3 +337,155 @@ async def test_all_callbacks_return_none(self, plugin):
             )
             is None
         )
+
+
+class TestAuditFieldsInLogMessages:
+    """Verify that audit context fields (user_id, org_id, order_id, request_id)
+    are included in log messages when contextvars are set."""
+
+    @pytest.fixture
+    def plugin(self):
+        with patch(
+            "lightspeed_agent.api.a2a.logging_plugin.get_settings"
+        ) as mock_settings:
+            settings = MagicMock()
+            settings.agent_logging_detail = "basic"
+            mock_settings.return_value = settings
+            yield AgentLoggingPlugin()
+
+    @pytest.fixture(autouse=True)
+    def _set_audit_context(self):
+        """Set audit contextvars for the duration of each test."""
+        token_user = _request_user_id.set("test-user-42")
+        token_org = _request_org_id.set("test-org-7")
+        token_order = _request_order_id.set("test-order-99")
+        token_req = _request_id.set("req-abc-123")
+        yield
+        _request_user_id.reset(token_user)
+        _request_org_id.reset(token_org)
+        _request_order_id.reset(token_order)
+        _request_id.reset(token_req)
+
+    @pytest.mark.asyncio
+    async def test_before_run_includes_audit_fields(self, plugin, caplog):
+        ctx = MagicMock()
+        ctx.invocation_id = "inv-1"
+        ctx.agent = MagicMock(name="agent")
+
+        with caplog.at_level(logging.INFO):
+            await plugin.before_run_callback(invocation_context=ctx)
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_after_run_includes_audit_fields(self, plugin, caplog):
+        ctx = MagicMock()
+        ctx.invocation_id = "inv-1"
+
+        with caplog.at_level(logging.INFO):
+            await plugin.after_run_callback(invocation_context=ctx)
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_before_model_includes_audit_fields(self, plugin, caplog):
+        ctx = MagicMock()
+        ctx.agent_name = "agent"
+
+        with caplog.at_level(logging.INFO):
+            await plugin.before_model_callback(
+                callback_context=ctx, llm_request=MagicMock()
+            )
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_after_model_includes_audit_fields(self, plugin, caplog):
+        ctx = MagicMock()
+        llm_response = MagicMock()
+        llm_response.usage_metadata = None
+        llm_response.model_version = None
+        llm_response.content = None
+
+        with caplog.at_level(logging.INFO):
+            await plugin.after_model_callback(
+                callback_context=ctx, llm_response=llm_response
+            )
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_before_tool_includes_audit_fields(self, plugin, caplog):
+        tool = MagicMock()
+        tool.name = "get_advisories"
+
+        with caplog.at_level(logging.INFO):
+            await plugin.before_tool_callback(
+                tool=tool, tool_args={}, tool_context=MagicMock()
+            )
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_after_tool_includes_audit_fields(self, plugin, caplog):
+        tool = MagicMock()
+        tool.name = "get_advisories"
+
+        with caplog.at_level(logging.INFO):
+            await plugin.after_tool_callback(
+                tool=tool, tool_args={}, tool_context=MagicMock(), result={}
+            )
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_tool_error_includes_audit_fields(self, plugin, caplog):
+        tool = MagicMock()
+        tool.name = "get_advisories"
+
+        with caplog.at_level(logging.ERROR):
+            await plugin.on_tool_error_callback(
+                tool=tool,
+                tool_args={},
+                tool_context=MagicMock(),
+                error=RuntimeError("fail"),
+            )
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text
+
+    @pytest.mark.asyncio
+    async def test_model_error_includes_audit_fields(self, plugin, caplog):
+        ctx = MagicMock()
+
+        with caplog.at_level(logging.ERROR):
+            await plugin.on_model_error_callback(
+                callback_context=ctx,
+                llm_request=MagicMock(),
+                error=RuntimeError("fail"),
+            )
+
+        assert "user_id=test-user-42" in caplog.text
+        assert "org_id=test-org-7" in caplog.text
+        assert "order_id=test-order-99" in caplog.text
+        assert "request_id=req-abc-123" in caplog.text