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

Set enableDebug = true in the [Config] section of your 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 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:

[Config]
enableDebug = true

3. Restart the Nitter process to reload the configuration:

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

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

curl http://localhost:8080/.health

Response structure:

{
  "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.

curl http://localhost:8080/.sessions

Example response:

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

Summary

• Set enableDebug = true in the [Config] section of 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}