Repository navigation
docs(adr): ADR-048 structured logging - #652
Conversation
One Frigg-owned logger port in core writes one redacted JSON record per line to stdout, with a fixed field set, six threshold levels, ADR-011 correlation ids and redaction by construction. Adds the register row and the roadmap entry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
d-klotz
added
release
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.
Once extra usage is available, comment @claude review on this pull request, or push a new commit, to trigger a review.
✅ Deploy Preview for friggframework-org ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 60de83654a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| The DLQ processor logs an unparsed body as its length and SHA-256 | ||
| (`dlq-processor.js:25,50`). |
There was a problem hiding this comment.
The proposed DLQ fingerprint will normally be a 64-character hexadecimal SHA-256 string (or a 44-character base64 string), both of which satisfy the preceding rule that scrubs base64-like runs of 40 or more characters in every string. Consequently malformed DLQ messages will record only [REDACTED:<len>] instead of the promised digest, preventing operators from grouping repeated payloads. Exempt the digest field from this pattern or use an encoding that the scrubber explicitly preserves.
Useful? React with 👍 / 👎.
seanspeaks
left a comment
seanspeaks
left a comment
There was a problem hiding this comment.
I'm approving since it looks thorough as a plan and covers a lot of the detailed basics.
The thing I want to call out for rationale:
-
It enables standardized logging in all Frigg implementations with default logging tooled up into the various components such that anyone debugging and monitoring a Frigg application can do so cleanly and from central docs without needing to explore how each repo or project may implement.
-
With that structured output, much easier to programmatically trace through and connect messages to db objects etc. making debugging much simpler.
-
Also lets us add outbound log destinations with a simple core extension that tackles the translation to the corresponding service with.
I think that last point deserves some notes/treatment here.
Answers the maintainer review on #652. Adds §11 log destinations: a destination sink supplies only translate and send, and core owns the buffer, the shared flush deadline and the failure rules. Makes the record contract additive-only from PR A, adds entityId and credentialId, and adds a central docs/guides/LOGGING.md to the sequencing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
|
@seanspeaks added §11 (log destinations) for your point 3: a sink only translates + sends, core owns buffer, flush and failures. Also |
|
🚀 PR was released in |
2 participants
Summary
Frigg has no logging standard. Core logs through 309 direct
console.*calls (plus 29 in admin-scripts), with no JSON, no levels and no shared correlation ids. ADR-011 names a "telemetry/logger abstraction" for logs, but the code never built the logs leg.The current logging also leaks secrets:
testAuthdumps the raw Lambda event:Authorization,x-frigg-*keys, cookies, the OAuthcodeand the login password (create-handler.js:167).FetchErrorputs the full URL with its query string in every stage. OnSTAGE=devit also adds request headers and bodies (Bearer tokens,client_secret).span.recordExceptionsends the same raw text to the trace backend.This ADR defines one logger for the framework.
What's in this PR
Documentation only. No code changes.
docs/architecture-decisions/048-structured-logging.md(new)docs/architecture-decisions/README.md(one row in Current ADRs)website/roadmap/data/adrs.json(one entry, count 30 → 31)The decision, in brief
One Frigg-owned logger port in core writes one redacted JSON record per line to stdout. Every record carries the same field set and the ADR-011 correlation ids.
getLogger(name),trace…fatal(message, fields),child(),isLevelEnabled().this.loggeronIntegrationBaseandRequesterfs.writeSyncto fd 1, notconsole.*timestamp,level,message,logger,requestId, ADR-011 ids,eventName,trace_id/span_id,errorFRIGG_LOG_LEVEL(defaultINFO,DEBUGon local runs)FetchErrorfixed at the source; no stage writes secrets@opentelemetry/api. Amends ADR-011 for the logs signalappDefinition.logging→ LambdaLoggingConfig+ retention. New apps get 30 daysno-console: errorin runtime packages, a redaction regression suite, require-graph guardsThe ADR also has a Usage examples section with integration, API module, core, test and log-query examples.
Needs a decision from the maintainers
The upgrade changes behavior, so it is an exception to the ADR-027 "no behavior change on upgrade" rule. The ADR lists 7 changes in the Negative consequences table (JSON replaces text,
FetchErrorloses query and dev detail, the debug replay stops, and others). A maintainer ratifies the whole list before PR A merges, as ADR-031 did.Sequencing
PR 0 (a dev-stack spike) → PR A (foundation, no call-site changes) → PR B (security-critical call sites) → devtools → area-by-area migration →
no-console: error.This PR supersedes #540: its OAuth-callback steps become redacted
DEBUGrecords. 048 is the first number no open PR claims (#644 claims 028–041, #646 claims 043, #648 claims 044–047).Test plan
Documentation only, so there is nothing to run.
website/roadmap/data/adrs.jsonpassespython3 -m json.toolpath:linecitations checked againstnext@ 99f6534🤖 Generated with Claude Code
📦 Published PR as canary version:
2.0.0--canary.652.b14f3b5.0✨ Test out this PR locally via:
npm install @friggframework/admin-scripts@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/core@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/devtools@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/eslint-config@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/prettier-config@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/schemas@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/serverless-plugin@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/test@2.0.0--canary.652.b14f3b5.0 npm install @friggframework/ui@2.0.0--canary.652.b14f3b5.0 # or yarn add @friggframework/admin-scripts@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/core@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/devtools@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/eslint-config@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/prettier-config@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/schemas@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/serverless-plugin@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/test@2.0.0--canary.652.b14f3b5.0 yarn add @friggframework/ui@2.0.0--canary.652.b14f3b5.0Version
Published prerelease version:
v2.0.0-next.111Changelog
🚀 Enhancement
@friggframework/admin-scripts,@friggframework/core,@friggframework/devtools,@friggframework/eslint-config,@friggframework/prettier-config,@friggframework/schemas,@friggframework/serverless-plugin,@friggframework/test,@friggframework/ui🐛 Bug Fix
@friggframework/coreAuthors: 3