Skip to content

Adopt the relay logging standard #81

Description

@barelyworkingcode

User story

As a developer diagnosing a failure, I want macMCP to log in the relay logging standard, so that I can follow one user action through every service by its trace ID.

Acceptance criteria

  1. The service writes one JSON object per line to stderr.
  2. Every JSON line carries the nine keys in logging-schema.json.
  3. The service reads its level from RELAY_LOG_LEVEL, and debug is off by default.
  4. Debug returns to info after 30 minutes and logs one warn line.
  5. macMCP writes logs to stderr only and never to stdout.
  6. macMCP reads _meta.trace_id in the tool-call branch.
  7. Each tool call logs one info line with the tool name.
  8. macMCP adds no _meta of its own.
  9. Each operation logs one info line when it ends, with op, status and duration_ms.
  10. No log line carries a prompt, a body, a token or other credentials.
  11. A test validates sample lines from the service against logging-schema.json.

What I'd notice

Nothing. Logs never reach a screen, a prompt or a message.

Simple door and power door

  • Simple: the everyday user sees no change.
  • Power: the developer searches one trace ID and reads this service's part of the path.

Context

macMCP is a stdio MCP server in Swift. It logs nothing today, and its stdout carries the protocol.

The contract is the logging standard (https://github.com/barelyworkingcode/relay/blob/main/docs/logging-standard.md) and its line schema (https://github.com/barelyworkingcode/relay/blob/main/docs/logging-schema.json), from relay PR 201 (merged). The standard is a contract, not shared code; this repo implements it in its own language. Parent: barelyworkingcode/relay#198.

Order: After relay captures stdio MCP stderr; otherwise its lines are lost.

Out of scope: rewriting log lines the repo does not otherwise change, and any shared library.

Contract

Cross-repo contract: barelyworkingcode/relay#202. Wave 2, and its real-app proof waits for relay R3 (stdio stderr capture).

Owns: Sources/macMCP/LogLine.swift, Sources/macMCP/main.swift (the tools/call branch only). Test writer owns: Tests/macMCPTests/LogLineTests.swift, with the schema fixture read via #filePath so Package.swift does not change.
Tasks: stderr-only writer; read _meta.trace_id in the tools/call branch (accept or create); one tool.call line per call with the tool name, status and duration_ms and no arguments; add nothing to result _meta.
Must not touch: Sources/macMCP/ResourceScope.swift, Sources/macMCP/ContextSchema.swift, Sources/macMCP/Services/**, Package.swift, any stdout write.
Proof: a test that the stdout bytes of a call are unchanged.
Verification: relay's tool-call-audited and acme-tools-through-bridge against the installed head.

Decisions made for the owner

  • Logging adoption order and scope follow the cross-repo contract on Adopt the relay logging standard relay#202.
  • The schema test uses a test-local keyword checker, not a library.
  • Amendment 1 (tightening, test fixture only): the schema fixture lives at Tests/Fixtures/logging-schema.json, outside the test target directory, so SwiftPM reports no unhandled-resource warning and Package.swift stays untouched.
  • Failed and denied tool calls log at warn, not info, so status and level agree per the standard.

Tasks

  • Add the stderr writer.
  • Read _meta.trace_id.
  • Add the per-call line.
  • Add the schema-validation test.

Gate

Enhancement that changes log output across repos. It needs owner review (needs-review).

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions