> For the complete documentation index, see [llms.txt](https://docs.envio.dev/llms.txt).

# Logging in Envio HyperIndex

Effective logging is essential for monitoring your blockchain indexer's performance, diagnosing issues, and gathering insights. The Envio indexer uses [pino](https://github.com/pinojs/pino/), a high-performance logging library for JavaScript. These logs can be integrated with analytics tools such as [Kibana](https://www.elastic.co/what-is/kibana) to generate metrics and visualizations.

## Table of Contents

- [User Logging](#users) - How to implement logging in your event handlers
- [Configuration & Output Formats](#metrics-debugging-and-troubleshooting) - Configuring log output and formats
- [Log Levels](#developer-logging) - Understanding available log levels
- [Troubleshooting](#troubleshooting) - Common issues and solutions

## Users

When implementing handlers for your indexer, use the logging functions provided in the context object. These functions allow you to record events and errors at different severity levels.

### Available Logging Methods

- `<context>.log.debug` - For detailed debugging information
- `<context>.log.info` - For general information about application flow
- `<context>.log.warn` - For potentially problematic situations
- `<context>.log.error` - For error events that might still allow the application to continue

### Examples by Language

```typescript
// Inside your handler
context.log.debug(
`Processing event with block hash: ${event.blockHash} (debug)`
);
context.log.info(`Processing event with block hash: ${event.blockHash} (info)`);
context.log.warn(`Potential issue with event: ${event.blockHash} (warn)`);
context.log.error(`Failed to process event: ${event.blockHash} (error)`);

// With exception:
context.log.error(
`Failed to process event: ${event.blockHash}`,
new Error("Error processing event")
);

// You can also provide an object as the second argument for structured logging:
context.log.info("Processing blockchain event", {
type: "info",
extra: "Additional debugging context",
data: { blockHash: event.blockHash },
});
```

## Metrics, Debugging, and Troubleshooting

The Envio indexer provides flexible logging configurations to suit different environments and use cases.

### Output Formats

The default output format is human-readable with color-coded log levels (`console-pretty`). You can modify the output format using environment variables:

```bash
# Available log strategies
LOG_STRATEGY="console-pretty"  # Default: Human-readable logs with colors in terminal
LOG_STRATEGY="ecs-file"        # ECS format logs to file (standard for Elastic Stack)
LOG_STRATEGY="ecs-console"     # ECS format logs to console
LOG_STRATEGY="file-only"       # Logs to file in Pino format (most efficient)
LOG_STRATEGY="console-raw"     # Raw Pino format logs to console
LOG_STRATEGY="both-prettyconsole"  # Pretty logs to console, Pino format to file

# Specify log file location when using file output
LOG_FILE="<path-to-log-file>"
```

For production environments or detailed analytics, consider integrating logs with Kibana or similar tools. We're developing Kibana dashboards for self-hosting and UI dashboards for our hosting solution. If you have specific dashboard requirements, please [contact us on Discord](https://discord.gg/envio).

## Developer Logging

### Log Levels

The indexer supports the following log levels in ascending order of severity:

```
- trace     # Most verbose level, detailed tracing information
- debug     # Debugging information for developers
- info      # General information about system operation
- udebug    # User-level debug logs
- uinfo     # User-level info logs
- uwarn     # User-level warning logs
- uerror    # User-level error logs
- warn      # System warning logs
- error     # System error logs
- fatal     # Critical errors causing system shutdown
```

> **Note**: Log levels prefixed with `u` (like `udebug`) are user-level logs emitted from the context for handlers or loaders.

### Configuring Log Levels

Set log levels using these environment variables:

```bash
LOG_LEVEL="info"      # Controls log level for console output (default: "info")
FILE_LOG_LEVEL="trace"  # Controls log level for file output (default: "trace")
```

Example:

```bash
export LOG_LEVEL="trace"  # Set console log level to the most verbose option
```

### Troubleshooting

When debugging issues in development:

1. **Terminal UI Issues**: The Terminal UI may sometimes hide errors. To disable it:

   ```bash
   export ENVIO_TUI="false"  # Or use --tui-off flag when starting
   ```

2. **Log Visibility**: To maintain the Terminal UI while capturing detailed logs:
   ```bash
   export LOG_STRATEGY="both-prettyconsole"
   export LOG_FILE="./debug.log"
   ```

This approach allows you to view essential information in the UI while capturing comprehensive logs for troubleshooting.

---