> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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

```typescript
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`): Lorsque la valeur est false, désactive pino-pretty et écrit des lignes JSON brutes (utile pour les agrégateurs de logs). (Default: `true`)

**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 :

```typescript
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 :

```typescript
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é.

```typescript
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

```typescript
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`.

```typescript
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

```typescript
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é.

```typescript
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 },
})
```