Registry / devops / mercurius-logging

mercurius-logging

library2.0.0jsnpmunverified

Fastify plugin that adds detailed GraphQL request logging to mercurius-based applications. Current stable version is 2.0.0, released 2024, compatible with Fastify v5. The plugin automatically logs GraphQL query names, mutation names, operation name, request body, and variables into structured JSON logs, addressing the default Fastify behavior that only logs a generic /graphql URL. Key differentiators: zero-config setup (plugin auto-detects GraphQL operations), optional fields for body/variables/alias, custom log levels, and use of request-scoped logger for correlation with request IDs. Ships TypeScript types.

devops

npm install mercurius-logging

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MERCURIUS-LOGGING

mercurius-logging

devopsjavascriptv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mercuriusLogging

✓ import mercuriusLogging from 'mercurius-logging'

✗ const mercuriusLogging = require('mercurius-logging');

ESM module; use default import.

mercuriusLogging

✓ import mLogging from 'mercurius-logging'

Can give any name as it is a default export.

MercuriusLoggingOptions

✓ import type { MercuriusLoggingOptions } from 'mercurius-logging'

TypeScript users should import the options type for configuration objects.

Set up a Fastify server with mercurius GraphQL and mercurius-logging plugin, enabling request body and variable logging.

import Fastify from 'fastify'; import mercurius from 'mercurius'; import mercuriusLogging from 'mercurius-logging'; const app = Fastify({ logger: true, disableRequestLogging: true }); const schema = ` type Query { add(x: Int!, y: Int!): Int! } `; const resolvers = { Query: { add: async (_, { x, y }) => x + y, }, }; await app.register(mercurius, { schema, resolvers }); await app.register(mercuriusLogging, { logLevel: 'info', logBody: true, logVariables: true, }); await app.listen({ port: 3000 });

Debug

Known issues

breakingVersion 2.x requires Fastify 5.x; version 1.x works with Fastify 4.x. Check compatibility table before upgrading.

fix

If using Fastify 4, install mercurius-logging@1.x. If using Fastify 5, upgrade to 2.x.

affects: >=2.0.0

gotchaPlugin requires a 'reply' object in context when using app.graphql() directly; otherwise logs are skipped.

fix

Always pass { reply } as context when calling app.graphql(query, { reply }).

affects: >=1.0.0

gotchaIf logBody or logVariables are enabled, sensitive data (e.g., passwords) in GraphQL variables may be logged. Ensure log level is appropriate or sanitize.

fix

Use logLevel to filter, or avoid enabling logBody/logVariables in production if sensitive data is present.

affects: >=1.0.0

deprecatedThe plugin does not support subscription logging (only queries and mutations). Subscription logs will not appear.

fix

No workaround; future versions may add subscription support.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'graphql')

mercurius not registered before mercurius-logging.

fix

Ensure app.register(mercurius, {...}) is called before app.register(mercuriusLogging, {...}).

Error: Fastify is not compatible with this plugin version - expecting Fastify version ^5.0.0

Using mercurius-logging v2 with an older Fastify version (<5).

fix

Either downgrade to mercurius-logging@1 or upgrade Fastify to v5.

MercuriusLogging is not a function

Using CommonJS require on an ESM-only module.

fix

Use import or dynamic import() syntax. For CommonJS projects, use await import('mercurius-logging') or switch to ESM.

Upgrade

Version history

2.0.0latest on npm

Audit

Dependencies

fastifyrequiredPlugin registers on Fastify instance, needs Fastify 5.x

mercuriusrequiredRequires mercurius to be registered first, logs GraphQL operations from it

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Eomm/mercurius-logging ↗

packagemercurius-logging ↗

homepagehttps://github.com/Eomm/mercurius-logging#readme ↗