Logging in @krakentech/blueprint-auth

The @krakentech/blueprint-auth package includes a logging system that allows consumers to control the verbosity of logs emitted by the package. This is particularly useful for debugging and monitoring authentication-related processes in your application.

Configuring Log Levels

You can set the log level by defining the BP_AUTH_LOG_LEVEL environment variable in your application's environment. The available log levels are:

• NONE: No logs will be emitted.
• ERROR: Only error messages will be logged.
• WARN: Warnings and error messages will be logged.
• INFO: Informational messages, warnings, and error messages will be logged.
• DEBUG: All messages, including debug information, will be logged.

By default, the log level is set to INFO, which means that INFO, WARN, and ERROR messages will be logged since they are of higher severity.

Custom GraphQL Error Severity

createGraphQLHandler converts failed Kraken GraphQL requests into blueprint-auth log entries. If some GraphQL failures are expected business outcomes for your application, use customization.getGraphQLErrorLogLevel to choose the log severity for each failure.

import { BlueprintAuthErrorCode } from "@krakentech/blueprint-auth";
import { createGraphQLHandler } from "@krakentech/blueprint-auth/server";

export default createGraphQLHandler({
  customization: {
    getGraphQLErrorLogLevel({ errorCode, cause }) {
      const messages = Array.isArray(cause)
        ? cause.map((krakenError) => krakenError?.message)
        : [];
      const isExpectedMeterPointOutcome =
        errorCode === BlueprintAuthErrorCode.OperationGraphQLUnknown &&
        messages.some((message) =>
          ["No meter point found", "Several meter points were found"].includes(
            message
          )
        );

      return isExpectedMeterPointOutcome ? "warn" : "error";
    },
  },
  krakenConfig: {
    graphqlAuthEndpoint: process.env.KRAKEN_GRAPHQL_AUTH_ENDPOINT,
    graphqlEndpoint: process.env.KRAKEN_GRAPHQL_ENDPOINT,
    xClientIpSecretKey: process.env.KRAKEN_X_CLIENT_IP_SECRET_KEY,
  },
  validation: {
    allowedRequestOrigins: ["https://www.example.com"],
  },
});

The callback receives { message, errorCode, cause, source }. cause holds whatever triggered the failure — for Kraken GraphQL errors this is the array of Kraken errors returned by the API, so narrow it (e.g. with Array.isArray) to inspect individual error messages. If the callback throws, or returns a value that isn't a recognised log level, the failure is logged as error by default.