Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
@carbon/logger
Centralized, isomorphic logger built on LogTape. Works in
browser and Node (SSR + Inngest jobs). Replaces raw console.* (the one
self-contained Deno edge function, embedding, cannot import workspace packages and
uses console directly). Structured records, hierarchical
categories, env-driven levels, and cloud-agnostic request-id correlation.
Always
- Get a logger with
getLogger(...segments)— it prepends thecarbonroot:getLogger("auth")→["carbon","auth"],getLogger("erp","sales")→["carbon","erp","sales"]. One logger per module/area. - Category convention: packages →
getLogger("<pkg>"); ERP modules →getLogger("erp","<module>"); MES →getLogger("mes",...); jobs →getLogger("jobs","<fnName>"). - Message + structured data:
logger.info("Created {id}", { id })or the object formlogger.info("{*}", { id, companyId }). Prefer structured properties over string concatenation — they survive to JSONL in prod. - Levels:
trace | debug | info | warning | error | fatal.LOG_LEVELenv overrides the default (devdebug, server prodinfo, browser prodwarning). - Request id is automatic inside loaders/actions/services:
requestIdMiddlewareputs{ requestId }into implicit context, so every server log during a request carries it. Read it withgetRequestId(context)from@carbon/logger/middleware.server, orgetRequestId()with no argument from a plain service function (resolved viarequestContextMiddleware's scope). - Request-scoped memoization:
oncePerRequest(key, fn)computes once per HTTP request;oncePerRead(key, fn)does the same but ONLY on GET/HEAD/OPTIONS. UseoncePerReadfor anything derived from database state — React Router runs an action and its loader revalidation in one request, so a plain memo there would serve pre-write data.oncePerRequestis for values that are not database state (e.g. a Supabase client). - Request-body logging is debug-only and guarded:
requestIdMiddlewarecaptures the body onto the access-log record'sbodyprop only whenLOG_LEVEL=debug(skipped entirely at the prodinfodefault — no clone, no parse). It coversPOST/PUT/PATCH/DELETEwithapplication/jsonorapplication/x-www-form-urlencodedbodies at/under 8KB (content-lengthrequired); multipart uploads, oversized, and unknown-length bodies log a short marker instead. Sensitive fields (password/token/secret/… — theREDACT_FIELD_PATTERNSset insrc/redaction.ts) are masked[REDACTED]in the captured object. That set is LogTape'sDEFAULT_REDACT_FIELDSminusemail/phone/address— ordinary ERP business data stays visible, and the prod sink MASKS matched fields rather than deleting them (a deleted key once made a PGRST204 failure unreconstructable from the log line). The body is read from a clone, so the route handler's stream stays intact.
Ask First
- Changing the sink/formatter setup in
config.server.ts/config.client.ts(affects every log line's shape — dev ANSI vs prod JSONL + field redaction). - Changing the category root or the
LOG_LEVELdefault derivation. - Adding a new log sink target (file, OTEL logs, Sentry) or a new trace exporter — these change deploy shape.
Never
- Import
./config.server,./middleware.server, or anything Node-only from client code. Node-only modules use the.server.tssuffix; the React Router Vite plugin errors at build if one reaches the client graph. - Depend on
@carbon/envfrom this package.@carbon/envthrows at module load on missing required vars; logging must stay importable in any context. It readsLOG_LEVEL/NODE_ENVraw viasrc/env.tsinstead. - Log at module top level. LogTape no-ops before
configure()runs, so load-time logs are dropped. Log inside functions/handlers.
Validation Commands
pnpm --filter @carbon/logger typecheck
pnpm --filter @carbon/logger test
Key Exports
| Subpath | Provides |
|---|---|
. |
getLogger, LOG_LEVELS, parseLogLevel, CarbonLogLevel, Logger type — isomorphic, safe everywhere |
./config.server |
ensureLoggingConfigured() (ANSI dev / JSONL+redacted prod, ALS) |
./config.client |
ensureLoggingConfigured() (plain console sink, no ALS) |
./middleware.server |
requestMiddleware (context + id + access log in one), requestIdMiddleware, requestIdContext, getRequestId, REQUEST_ID_HEADER, plus the request-context API re-exported from context.server: requestContextMiddleware, getRouterContext, getRequestContext, oncePerRequest, oncePerRead |
./tracing.server |
createTracing({ serviceName, afterRequest }) — React Router instrumentations (OpenTelemetry); annotateRequestSpan(attributes); nameRequestSpan(name); timedMiddleware({ name: fn }); withSpan(name, attributes, run); queryLog — Kysely log hook, undefined when tracing is off |
./inngest |
createInngestLogger() — adapter passed to new Inngest({ logger }) |
Wiring (per app)
entry.server.tsx:import { ensureLoggingConfigured } from "@carbon/logger/config.server"; ensureLoggingConfigured();at top.entry.client.tsx: same from@carbon/logger/config.client.entry.server.tsxalso exportsinstrumentations = createTracing({ serviceName: "carbon-erp", afterRequest }).root.tsx:export const middleware = timedMiddleware({ request: requestMiddleware, security: securityMiddleware, flash: flashMiddleware })—requestMiddlewareis the request scope in one middleware (context + request id + access log) (request context FIRST so every downstream middleware and handler runs inside the AsyncLocalStorage scope, then request id so downstream logs carry it).
Tracing (OpenTelemetry)
src/tracing.server.ts. Off unless enabled: with no
OTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT),
createTracing returns [], no provider or fetch
instrumentation is registered, queryLog is undefined so Kysely installs no
hook, and annotateRequestSpan returns immediately. The library code is loaded
but nothing in it runs.
Nothing here is specific to a vendor or host. Configuration is the standard OTel variables, read by the exporter and SDK themselves, so any OTLP backend works:
# Axiom — the host is your Axiom edge domain (api.axiom.co is the US default)
OTEL_EXPORTER_OTLP_ENDPOINT="https://api.axiom.co"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20<api-token>,X-Axiom-Dataset=<dataset>"
# optional
OTEL_SERVICE_NAME="carbon-erp" # default: the app's serviceName
OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production,service.version=<sha>"
OTEL_TRACES_SAMPLER="parentbased_traceidratio" # default: every request
OTEL_TRACES_SAMPLER_ARG="0.1"
One trace per request:
Request span (
SERVER) — named by method until a route handler reports the matched pattern, thenGET /x/part/:itemId/details. Carrieshttp.route,url.path, and — set byrequestIdMiddlewarethroughannotateRequestSpan—http.response.status_codeandcarbon.request_id(the id on every log line of that request). React Router 7.18's request instrumentation reports neither the status nor the pattern, which is why they arrive from those two places. A route that serves many things on one path renames it withnameRequestSpan:POST /api/inngest carbon-event-queue,POST /api/mcp call_tool sales_getCustomers,POST /api/v1/sales/getCustomers. Only known function ids and operations go into the name; the same values are oninngest.function.id/carbon.operationfor grouping.loader|action <routeId>spans, one per route handler. Middleware get no span: a middleware span contains everything after it, so it read as slow whenever a loader was. The apps wrap the root list intimedMiddleware({ name: fn, ... }), which records each middleware's OWN time on the request span ascarbon.middleware.<name>.ms(its total minus the time in what it calls next). Named by key, notfn.name: the production build minifies function names.Fetch spans from
@opentelemetry/instrumentation-undici, only for fetches made inside a request (requireParentforSpans).fetchSpanNamenames a Supabase call by what it does —GET /rest/v1/methodMaterial,storage download,auth GET user,function get-method— and anything else by host. Names never carry ids, bucket names or file paths; those are onurl.path.url.fullandurl.queryget the access log'sredactSearchmasking.Operation spans, from
withSpan. Every Carbon API operation runs through its oRPC procedure (api+/v1+/lib/router.server.ts), whose outermost middleware opensoperation sales_getCustomers— so the HTTP API, MCPcall_tool, the agent and workflows are all named in one place. The MCP server (@carbon/ee/mcp.server) wrapsregisterToolto openmcp call_tool sales_getCustomers/mcp search_toolsaround each tool call. Both also setcarbon.operation(andcarbon.mcp.tool) on the request span, so a request can be grouped by what it ran without joining spans.Query spans for Kysely, from
queryLogpassed as Kysely'sloghook at the three places a client is built (apps/{erp,mes}/app/services/database.server.ts,packages/jobs/src/db.ts, throughgetPostgresClient's third argument). NamedSELECT item/INSERT jobMaterial— the verb and the first quoted table — with the SQL indb.query.text. Bound parameter values are never recorded. Kysely reports a query after it ran, so the span is back-dated by the measured duration, which covers the query but not the wait for a pooled connection, andBEGIN/COMMITare not reported at all.
Not traced: Redis, and anything that talks HTTP through Node's http module
rather than fetch. That time shows up inside the enclosing loader or action span.
The batch is exported on a timer (every 5 s by default, OTEL_BSP_* to tune).
A host that suspends the process once a response is sent would strand it, so
createTracing takes an optional afterRequest(flush); the apps pass one only
when VERCEL is set, handing the flush to waitUntil from @vercel/functions.
That host-specific line lives in each app's entry.server.tsx, not here.
Cross-References
packages/lib/src/inngest/client.ts— consumescreateInngestLogger().packages/env/— definesLOG_LEVEL(also exposed towindow.env).