Rapid7 Insight Python Logger

1.0.1 · maintenance · verified Thu Apr 16

r7insight-python is a plugin library designed to integrate Python's standard logging module with Rapid7 Insight (formerly InsightOps). It enables sending log messages, and optionally method execution times, CPU, and memory statistics to your Rapid7 Insight account. The library leverages asynchronous operations for log dispatch and is currently at version 1.0.1. Releases appear to be infrequent, suggesting a mature or maintenance phase.

Common errors

```
LE: Unable to connect to R7Insight.
```
cause This error typically indicates a network connectivity issue to the Rapid7 Insight ingest server, often due to firewall rules, incorrect proxy settings, or TLS negotiation failures.

fix Verify that your server has outbound access to the Rapid7 Insight ingest endpoint on port 443 (or 80 if `use_tls=False`). Check local firewall, corporate proxy, and DNS resolution. Setting `use_tls=False, allow_plaintext_fallback=True` in `R7InsightHandler` can help diagnose if TLS is the specific issue, but should be used with caution.
```
Logs are not appearing in Rapid7 Insight.
```
cause This can be due to an incorrect Insight Token, wrong region, a misconfigured log source (not 'Token TCP'), network issues preventing asynchronous delivery, or simply not waiting long enough for logs to process.

fix Double-check the `TOKEN` and `REGION` values passed to `R7InsightHandler`. Ensure your log source in Rapid7 Insight is configured as 'Token TCP'. Confirm there are no 'Unable to connect' messages in your application logs. Remember the appender is asynchronous, so a delay is expected.

Warnings

gotcha The r7insight-python appender is asynchronous. Logs are queued and sent in the background, which means they might not appear immediately in your Rapid7 Insight account. Do not expect synchronous delivery.
Fix: Account for asynchronous delivery in testing and production; allow time for logs to be processed and appear in the Insight console.
gotcha Correct configuration requires a 'Token TCP' log source in your Rapid7 Insight account. Using the wrong source type or an incorrect token will prevent logs from being received.
Fix: Ensure you create a log in Rapid7 Insight, select 'Token TCP' as the source type, and use the generated Token UUID and the correct region (e.g., 'us', 'eu') when initializing `R7InsightHandler`.
gotcha TLS (SSL) connection issues are a common point of failure. The library attempts to send logs over TLS on port 443 by default. Some environments may experience issues, leading to 'Unable to connect' errors.
Fix: Check network firewalls and proxy settings. As a last resort, for debugging or non-sensitive data, you can set `use_tls=False` and `allow_plaintext_fallback=True` in the `R7InsightHandler` constructor, but this sends logs over plain HTTP on port 80 and is not recommended for production. Example: `R7InsightHandler(TOKEN, REGION, use_tls=False, allow_plaintext_fallback=True)`.
deprecated While PyPI classifiers for version 1.0.1 list Python 2 compatibility, active development and best practices strongly suggest using Python 3. Rapid7's other related Python projects have moved to Python 3.8+ or higher.
Fix: Use Python 3.x for new projects. If migrating from Python 2, ensure all code is Python 3 compatible before using this library.

Install

pip install r7insight_python Install latest version

Imports

R7InsightHandler
```
from r7insight import R7InsightHandler
```
metrics
```
from r7insight import metrics
```
Used for the @metrics.Metric() decorator

Quickstart

This quickstart demonstrates basic logging to Rapid7 Insight. You need to obtain a Token UUID from a 'Token TCP' log source in your Rapid7 Insight account and specify your region. The example retrieves these values from environment variables or uses placeholders.

import logging
import os
from r7insight import R7InsightHandler

# Get Rapid7 Insight Token and Region from environment variables
# Ensure you configure a 'Token TCP' log source in your Rapid7 Insight account.
TOKEN = os.environ.get('R7INSIGHT_TOKEN', 'YOUR_RAPID7_TOKEN')
REGION = os.environ.get('R7INSIGHT_REGION', 'us') # e.g., 'us', 'eu', 'ca', 'au', 'jp', 'in', 'uk'

# Basic logging setup
log = logging.getLogger('r7insight')
log.setLevel(logging.INFO)

try:
    handler = R7InsightHandler(TOKEN, REGION)
    log.addHandler(handler)
    log.info("Hello from r7insight-python!")
    log.warning("This is a warning message.")
    log.error("An error occurred!")
    print("Logs sent to Rapid7 Insight (asynchronously).")
    print("Check your Rapid7 Insight account for these messages.")
except Exception as e:
    print(f"Failed to configure R7InsightHandler: {e}")
    print("Please ensure R7INSIGHT_TOKEN and R7INSIGHT_REGION are correctly set.")

view raw JSON →