PinoLogger

Une instance de logger est créée au moyen de new PinoLogger() et fournit des méthodes permettant d’enregistrer des événements selon leur niveau de gravité.

Exemple d’utilisation

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
  }),
})

Paramètres

name:

string

Libellé utilisé pour regrouper et identifier les logs de ce logger.

level:

"debug" | "info" | "warn" | "error"

Définit le niveau de log minimal. Les messages inférieurs à ce niveau sont ignorés.

transports:

Record<string, LoggerTransport>

Table de correspondance des instances de transport utilisées pour conserver les logs.

overrideDefaultTransports?:

boolean

Si la valeur est true, désactive le transport console par défaut.

formatters?:

pino.LoggerOptions['formatters']

Formatteurs Pino personnalisés pour la sérialisation des logs.

redact?:

pino.LoggerOptions['redact']

Chemins ou options permettant de masquer les champs sensibles dans la sortie des logs (redact de Pino).

prettyPrint?:

boolean

= true

Lorsque la valeur est false, désactive pino-pretty et écrit des lignes JSON brutes (utile pour les agrégateurs de logs).

mixin?:

pino.MixinFn

Fonction mixin de Pino fusionnée dans chaque objet de log (par exemple, un traceId limité à la requête ou d’autres métadonnées partagées).

customLevels?:

Record<string, number>

Niveaux de log personnalisés et valeurs numériques transmis à Pino. La gravité standard reste consignée au moyen de debug, info, warn et error ; les niveaux supplémentaires suivent le comportement des niveaux personnalisés de Pino.

Enrichissement des logs avec mixin

Utilisez mixin lorsque vous souhaitez inclure les mêmes champs structurés dans chaque ligne, par exemple afin de les corréler avec le reste de vos services :

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

function getTraceContext() {
  return { traceId: 'abc-123' }
}

export const mastra = new Mastra({
  logger: new PinoLogger({
    name: 'Mastra',
    level: 'info',
    mixin() {
      return getTraceContext()
    },
  }),
})

Niveaux personnalisés

customLevels est transmis à Pino. PinoLogger expose uniquement debug, info, warn et error ; pour tout nom de niveau supplémentaire, par exemple audit, créez une sous-classe et transmettez-le à l’instance Pino sous-jacente :

src/mastra/logger.ts

import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'

type AuditLevel = 'audit'

class MastraPinoWithAudit extends PinoLogger<AuditLevel> {
  audit(message: string, meta: Record<string, unknown> = {}) {
    this.logger.audit(meta, message)
  }
}

const logger = new MastraPinoWithAudit({
  name: 'Mastra',
  level: 'info',
  customLevels: { audit: 35 },
})

export const mastra = new Mastra({ logger })

Les valeurs numériques suivent l’ordre de Pino, dont les niveaux intégrés utilisent les valeurs 10 à 60. Le niveau 35 se situe entre info (30) et warn (40) ; avec level: 'info', les lignes info et audit sont donc toutes deux émises.

Transport par fichier (logs structurés)

Écrit des logs structurés dans un fichier au moyen de FileTransport. Le logger accepte un message brut comme premier argument et des métadonnées structurées comme second argument. Ces données sont converties en interne en BaseLogMessage, puis conservées dans le chemin de fichier configuré.

src/mastra/loggers/file-transport.ts

import { FileTransport } from '@mastra/loggers/file'
import { PinoLogger } from '@mastra/loggers/pino'

export const fileLogger = new PinoLogger({
  name: 'Mastra',
  transports: { file: new FileTransport({ path: 'test-dir/test.log' }) },
  level: 'warn',
})

Utilisation du transport par fichier

fileLogger.warn('Low disk space', {
  destinationPath: 'system',
  type: 'WORKFLOW',
})

Transport Upstash (collecteur de logs distant)

Diffuse des logs structurés vers une liste Redis distante au moyen d’UpstashTransport. Le logger accepte un message sous forme de chaîne et un objet de métadonnées structurées. Il permet de centraliser les logs dans les environnements distribués et de les filtrer selon destinationPath, type et runId.

src/mastra/loggers/upstash-transport.ts

import { UpstashTransport } from '@mastra/loggers/upstash'
import { PinoLogger } from '@mastra/loggers/pino'

export const upstashLogger = new PinoLogger({
  name: 'Mastra',
  transports: {
    upstash: new UpstashTransport({
      listName: 'production-logs',
      upstashUrl: process.env.UPSTASH_URL!,
      upstashToken: process.env.UPSTASH_TOKEN!,
    }),
  },
  level: 'info',
})

Utilisation du transport Upstash

upstashLogger.info('User signed in', {
  destinationPath: 'auth',
  type: 'AGENT',
  runId: 'run_123',
})

Transport personnalisé

Vous pouvez créer des transports personnalisés à l’aide de l’utilitaire createCustomTransport afin de les intégrer à n’importe quel service ou flux de logs.

Exemple de transport Sentry

Crée un transport personnalisé au moyen de createCustomTransport et l’intègre à un flux de logs tiers tel que pino-sentry-transport. Cela permet de transmettre les logs à un système externe comme Sentry pour bénéficier de fonctionnalités avancées de supervision et d’observabilité.

src/mastra/loggers/sentry-transport.ts

import { createCustomTransport } from '@mastra/core/loggers'
import { PinoLogger } from '@mastra/loggers/pino'
import pinoSentry from 'pino-sentry-transport'

const sentryStream = await pinoSentry({
  sentry: {
    dsn: 'YOUR_SENTRY_DSN',
    _experiments: {
      enableLogs: true,
    },
  },
})

const customTransport = createCustomTransport(sentryStream)

export const sentryLogger = new PinoLogger({
  name: 'Mastra',
  level: 'info',
  transports: { sentry: customTransport },
})