# Logging

Using the context's log object (`c.log`) allows you to log complex data using structured logging.

Using the actor logging API is completely optional.

## Log levels

There are 7 log levels:

| Level  | Call                            | Description                                                      |
| ------ | ------------------------------- | ---------------------------------------------------------------- |
| Fatal  | `c.log.fatal(message, ...args);`   | Critical errors that prevent core functionality                 |
| Error  | `c.log.error(message, ...args);`    | Errors that affect functionality but allow continued operation  |
| Warn   | `c.log.warn(message, ...args);`     | Potentially harmful situations that should be addressed         |
| Info   | `c.log.info(message, ...args);`     | General information about significant events & state changes    |
| Debug  | `c.log.debug(message, ...args);`    | Detailed debugging information, usually used in development     |
| Trace  | `c.log.trace(message, ...args);`    | Very detailed debugging information, usually for tracing flow   |
| Silent | N/A                             | Disables all logging output                                     |

## Structured logging

The built-in logging API (using `c.log`) provides structured logging to let you log key-value
pairs instead of raw strings. Structured logs are readable by both machines &
humans to make them easier to parse & search.

When using `c.log`, the actor's name, key, and actor ID are automatically included in every log output. This makes it easy to filter and trace logs by specific actors in production environments.

### Examples

examples/docs/general-logging/log-examples.ts:

```ts
import { actor } from "rivetkit";

const myActor = actor({
  state: {},
  actions: {
    logExamples: (c) => {
      // Just a message
      c.log.info('server started');
      // Prints: level=INFO actor=myActor key=foo actorId=44096d46632fd087 msg="server started"

      // Object with message and additional fields
      c.log.info({ msg: 'user connected', userId: 123, ip: '192.168.1.1' });
      // Prints: level=INFO actor=myActor key=foo actorId=44096d46632fd087 msg="user connected" userId=123 ip="192.168.1.1"

      // Just an object (no message)
      c.log.info({ action: 'purchase', amount: 99.99, currency: 'USD' });
      // Prints: level=INFO actor=myActor key=foo actorId=44096d46632fd087 action="purchase" amount=99.99 currency="USD"
    }
  }
});
```

The logging system is built on [Pino](https://getpino.io/#/docs/api?id=logger), a high-performance structured logger for Node.js.

## Configuration

### Environment Variables

You can configure logging behavior using environment variables:

| Variable | Description | Values | Default |
| -------- | ----------- | ------ | ------- |
| `RIVET_LOG_LEVEL` | Sets the minimum log level to display | `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `silent` | `warn` |
| `RIVET_LOG_TARGET` | Include the module name that logged the message | `1` to enable, `0` to disable | `0` |
| `RIVET_LOG_TIMESTAMP` | Include timestamp in log output | `1` to enable, `0` to disable | `0` |
| `RIVET_LOG_MESSAGE` | Enable detailed message logging for debugging | `1` to enable, `0` to disable | `0` |
| `RIVET_LOG_ERROR_STACK` | Include stack traces in error output | `1` to enable, `0` to disable | `0` |
| `RIVET_LOG_HEADERS` | Log HTTP headers in requests | `1` to enable, `0` to disable | `0` |

Example:
```bash
RIVET_LOG_LEVEL=debug RIVET_LOG_TARGET=1 RIVET_LOG_TIMESTAMP=1 node server.js
```

### Log Level

You can configure the log level programmatically when setting up your registry:

examples/docs/general-logging/log-level.ts:

```ts
import { actor, setup } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c) => c.state.count++ }
});

const registry = setup({
  use: { counter },
  logging: {
    level: "debug"
  }
});
```

### Custom Pino Logger

You can also provide a custom Pino base logger for more advanced logging configurations:

examples/docs/general-logging/custom-pino.ts:

```ts
import { actor, setup } from "rivetkit";
import { pino } from "pino";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c) => c.state.count++ }
});

const customLogger = pino({
  level: "info",
  transport: {
    target: "pino-pretty"
  }
});

const registry = setup({
  use: { counter },
  logging: {
    baseLogger: customLogger,  // Use your custom Pino logger
  }
});
```

If using a custom base logger, you must manually configure your own log level in the Pino logger.

For more advanced Pino configuration options, see the [Pino API documentation](https://getpino.io/#/docs/api?id=export).

### Disable Welcome Message

You can disable the default RivetKit welcome message with:

examples/docs/general-logging/disable-welcome.ts:

```ts
import { actor, setup } from "rivetkit";

const counter = actor({
  state: { count: 0 },
  actions: { increment: (c) => c.state.count++ }
});

const registry = setup({
  use: { counter },
  noWelcome: true
});
```