# How to Enable and View Nitter's Session Logging for Debugging

> Debug Nitter easily by enabling session logging. Learn how to set enableDebug to true in nitter.conf for real-time diagnostics and monitoring. Improve your Nitter experience today.

- Repository: [Zed/nitter](https://github.com/zedeus/nitter)
- Tags: how-to-guide
- Published: 2026-08-29

---

**Set `enableDebug = true` in the `[Config]` section of your [`nitter.conf`](https://github.com/zedeus/nitter/blob/main/nitter.conf) file to activate real-time session diagnostics, console logging, and HTTP endpoints for monitoring authentication pool health.**

Nitter is a free and open-source alternative Twitter front-end written in Nim. When troubleshooting authentication issues or rate limiting, you may need to inspect the internal state of Nitter's guest and OAuth token pools. This guide explains how to enable and view Nitter's session logging for debugging by toggling a single configuration flag that unlocks detailed observability into the authentication layer.

## Enabling the Debug Configuration Flag

The session logging system is controlled by the `enableDebug` boolean in the server configuration. According to the source code in `src/config.nim`, this parameter defaults to `false` and must be explicitly enabled.

To activate debug mode:

1. Open your [`nitter.conf`](https://github.com/zedeus/nitter/blob/main/nitter.conf) file (or set the `NITTER_CONF_FILE` environment variable to point to your configuration).
2. Locate the `[Config]` section and add or modify the following line:

```ini
[Config]
enableDebug = true

```

3. Restart the Nitter process to reload the configuration:

```bash

# For systemd deployments

sudo systemctl restart nitter

# For manual execution

./nitter

```

Once restarted, the server invokes `createDebugRouter(cfg)` from `src/nitter.nim`, which conditionally registers the debug HTTP routes based on the `cfg.enableDebug` value.

## Monitoring Session Logs in Console Output

With debugging enabled, Nitter emits structured log lines prefixed with `[sessions]` to standard output. These messages are generated by the `log` template defined in `src/auth.nim` and provide real-time visibility into token rotation, rate limit status, and session invalidation.

Typical log entries include:

```text
[sessions] resetting limit: 1234567890 (user123)
[sessions] rate limited by api: tweet, reqs left: 4, oauth user123
[sessions] invalidating: cookie 9876543210 (user456)

```

Monitor these logs by viewing the process output directly or through your process manager's logging facility (e.g., `journalctl -u nitter -f` for systemd).

## Querying Debug HTTP Endpoints

When `enableDebug` is active, Nitter exposes two administrative endpoints that return JSON diagnostics about the authentication pool. These routes are implemented in `src/routes/debug.nim` and provide structured data suitable for monitoring dashboards or manual inspection.

### Health Endpoint (/.health)

The `/.health` endpoint returns aggregate statistics about active sessions and API request distribution:

```bash
curl http://localhost:8080/.health

```

Response structure:

```json
{
  "sessions": { 
    "total": 5, 
    "limited": 1, 
    "oauth": { 
      "total": 3, 
      "limited": 0 
    }
  },
  "requests": { 
    "total": 42, 
    "apis": { 
      "tweet": 12, 
      "profile": 5 
    } 
  }
}

```

### Sessions Endpoint (/.sessions)

The `/.sessions` endpoint provides a detailed per-session breakdown, including rate limit remaining counts and reset timestamps. **Note:** This endpoint is strictly guarded by the `cfg.enableDebug` check and returns 404 when debugging is disabled.

```bash
curl http://localhost:8080/.sessions

```

Example response:

```json
{
  "1234567890": {
    "kind": "oauth",
    "apis": { 
      "tweet": { 
        "remaining": 4, 
        "reset": 1728394000 
      } 
    },
    "pending": 0,
    "limited": false
  }
}

```

## Summary

- Set **`enableDebug = true`** in the `[Config]` section of [`nitter.conf`](https://github.com/zedeus/nitter/blob/main/nitter.conf) to activate diagnostics.
- Restart Nitter to load the configuration and register the **debug router**.
- Watch console output for **`[sessions]`** prefixed log lines emitted by `src/auth.nim`.
- Query **`/.health`** for aggregate pool statistics and **`/.sessions`** for detailed token-level data.
- Both endpoints are defined in `src/routes/debug.nim` and only accessible when debugging is enabled.

## Frequently Asked Questions

### What is the enableDebug flag in Nitter?

The `enableDebug` flag is a configuration option defined in `src/config.nim` that activates Nitter's diagnostic mode. When set to `true`, it enables the `createDebugRouter` function in `src/nitter.nim` to register the `/.health` and `/.sessions` endpoints, and allows the `log` template in `src/auth.nim` to print session-related debug information to standard output.

### Where are Nitter session logs stored?

Nitter session logs are written to **standard output** (stdout) rather than a dedicated file. When `enableDebug` is active, you will see lines prefixed with `[sessions]` in the console or system journal where the Nitter process is running. For persistent storage, configure your process manager (systemd, Docker, etc.) to capture and rotate stdout.

### How do I access the Nitter sessions endpoint?

Access the `/.sessions` endpoint by sending an HTTP GET request to `http://your-nitter-instance/.sessions`. This endpoint is only available when `enableDebug` is enabled in the configuration; otherwise, Nitter returns a 404 error. The endpoint returns a JSON object mapping session IDs to their current rate limit status, token type, and pending request counts.

### Is it safe to enable debug mode in production?

While enabling `enableDebug` exposes detailed session information through the `/.sessions` endpoint, it does not expose sensitive credentials like OAuth tokens or passwords. However, the endpoint reveals internal pool statistics and user session identifiers that could aid attackers in understanding your rate limiting capacity. Restrict access to these endpoints using a reverse proxy or firewall rules if enabling in production environments.