pygraylog

https://github.com/zmallen/pygraylog
Admin
pygraylog is a lightweight Python wrapper for the Graylog 2.0 API that provides standard access to...
Tokens:5,585
Snippets:39
Trust Score:7
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install pygraylog via pip

Source: https://github.com/zmallen/pygraylog/blob/master/README.md

Install the pygraylog library using pip for use as a dependency in your Python projects.

```bash
pip install pygraylog
```

--------------------------------

### Import GraylogAPI Class

Source: https://github.com/zmallen/pygraylog/blob/master/README.md

Import the necessary class from the pygraylog library to start using its functionalities.

```python
from pygraylog.graylogapi import GraylogAPI
```

--------------------------------

### Initialize GraylogAPI Client

Source: https://context7.com/zmallen/pygraylog/llms.txt

Instantiate the GraylogAPI client with the Graylog server URL and authentication credentials. Either username/password or an API key must be provided.

```python
from pygraylog.graylogapi import GraylogAPI

# Username / password authentication
api = GraylogAPI('https://graylog.example.com:12900',
                 username='admin',
                 password='s3cr3t')

# Token-based authentication (recommended for production)
api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='xopqoiwepmd1o23m9awuaspofp')

# Supplying both raises ValueError
try:
    bad = GraylogAPI('https://graylog.example.com:12900',
                     username='admin',
                     api_key='sometoken')
except ValueError as e:
    print(e)  # username / api_key cannot be provided at same time
```

--------------------------------

### Initialize GraylogAPI with API Key

Source: https://github.com/zmallen/pygraylog/blob/master/README.md

Instantiate the GraylogAPI class using your Graylog server's base URL and an API key for token-based authentication. This is recommended for better security.

```python
api = pygraylog.GraylogAPI('https://localhost:12900', api_key='xopqoiwepmd1o23m9awuaspofp')
```

--------------------------------

### Initialize GraylogAPI with Username and Password

Source: https://github.com/zmallen/pygraylog/blob/master/README.md

Instantiate the GraylogAPI class using your Graylog server's base URL, username, and password for authentication.

```python
api = pygraylog.GraylogAPI('https://localhost:12900', username='foo', password='foo')
```

--------------------------------

### GraylogAPI Constructor

Source: https://context7.com/zmallen/pygraylog/llms.txt

Instantiates an API client bound to a Graylog base URL. Supports username/password or API key authentication.

```APIDOC
## GraylogAPI Constructor

`GraylogAPI(url, username=None, password=None, api_key=None)`

Instantiates an API client bound to a Graylog base URL. Exactly one of username/password or api_key must be supplied; providing both raises a `ValueError`. The `url` parameter sets the Graylog server base URL (e.g. `https://localhost:12900`).

### Parameters
- **url** (string) - Required - The Graylog server base URL.
- **username** (string) - Optional - The username for authentication.
- **password** (string) - Optional - The password for authentication.
- **api_key** (string) - Optional - The API key for authentication.

### Request Example
```python
from pygraylog.graylogapi import GraylogAPI

# Username / password authentication
api = GraylogAPI('https://graylog.example.com:12900',
                 username='admin',
                 password='s3cr3t')

# Token-based authentication (recommended for production)
api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='xopqoiwepmd1o23m9awuaspofp')

# Supplying both raises ValueError
try:
    bad = GraylogAPI('https://graylog.example.com:12900',
                     username='admin',
                     api_key='sometoken')
except ValueError as e:
    print(e)  # username / api_key cannot be provided at same time
```
```

--------------------------------

### search.universal.absolute.get

Source: https://context7.com/zmallen/pygraylog/llms.txt

Searches Graylog messages within a specific start/end datetime range. Supports optional parameters like limit and offset.

```APIDOC
## search.universal.absolute.get — Absolute Time Range Search

Searches Graylog messages within a specific start/end datetime range. Required parameters are `fields`, `query`, `from_`, and `to`. The trailing underscore on `from_` avoids Python's `from` keyword — pygraylog automatically strips it before sending the HTTP request. Optional parameters (e.g. `limit`, `offset`, `filter`) can be passed freely as additional keyword arguments.

### Method
GET

### Endpoint
/api/search/universal/absolute

### Parameters
#### Path Parameters
None

#### Query Parameters
- **fields** (string) - Required - Comma-separated list of fields to return.
- **query** (string) - Required - The search query string (e.g., '*').
- **from_** (string) - Required - The start of the date range (e.g., 'YYYY-MM-DD HH:MM:SS').
- **to** (string) - Required - The end of the date range (e.g., 'YYYY-MM-DD HH:MM:SS').
- **limit** (integer) - Optional - The maximum number of results to return.
- **offset** (integer) - Optional - The offset for pagination.
- **filter** (string) - Optional - Additional filter for the search.

### Request Example
```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='xopqoiwepmd1o23m9awuaspofp')

# Search all messages in a date window, returning the 'src_ip' field
result = api.search.universal.absolute.get(
    fields='src_ip',
    query='*',
    from_='2024-01-01 00:00:00',
    to='2024-01-01 23:59:59',
    limit=100,        # optional
    offset=0          # optional
)
print(result)  # JSON string response from Graylog
```

### Response
#### Success Response (200)
- **response** (string) - JSON string response from Graylog containing search results.
```

--------------------------------

### Handle Missing Required Fields with ValueError

Source: https://context7.com/zmallen/pygraylog/llms.txt

Demonstrates how a missing required field (like 'from_' or 'to') for the search.universal.absolute.get endpoint raises a ValueError.

```python
try:
    api.search.universal.absolute.get(
        fields='src_ip',
        query='*'
        # from_ and to are missing
    )
except ValueError as e:
    print(e)
    # Not all required arguments passed for /search/universal/absolute.
    # Given: ['fields', 'query']
    # Required: ['fields', 'query', 'from_', 'to']
```

--------------------------------

### Build Authentication Header

Source: https://context7.com/zmallen/pygraylog/llms.txt

Constructs the necessary HTTP Authorization and Accept headers for API requests. Handles both token-based and username/password authentication.

```python
from pygraylog.graylogapi import GraylogAPI
import base64

# Token-based header
api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='mytoken123')
header = api.build_auth_header()
# header == {
#   'Authorization': 'Basic ' + base64.b64encode('mytoken123:token'),
#   'Accept': 'application/json'
# }
print(header)

# Username/password header
api2 = GraylogAPI('https://graylog.example.com:12900',
                  username='admin', password='s3cr3t')
header2 = api2.build_auth_auth_header()
# header2 == {
#   'Authorization': 'Basic ' + base64.b64encode('admin:s3cr3t'),
#   'Accept': 'application/json'
# }
print(header2)
```

--------------------------------

### build_auth_header

Source: https://context7.com/zmallen/pygraylog/llms.txt

Constructs the HTTP Authorization and Accept headers used in every request.

```APIDOC
## build_auth_header

`build_auth_header()`

Constructs the HTTP `Authorization` (Basic) and `Accept` headers used in every request. When an `api_key` is set, the credential is formatted as `<api_key>:token` before Base64 encoding; otherwise it uses `<username>:<password>`.

### Returns
- **dict** - A dictionary containing the 'Authorization' and 'Accept' headers.

### Request Example
```python
from pygraylog.graylogapi import GraylogAPI
import base64

# Token-based header
api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='mytoken123')
header = api.build_auth_header()
# header == {
#   'Authorization': 'Basic ' + base64.b64encode('mytoken123:token'),
#   'Accept': 'application/json'
# }
print(header)

# Username/password header
api2 = GraylogAPI('https://graylog.example.com:12900',
                  username='admin', password='s3cr3t')
header2 = api2.build_auth_header()
# header2 == {
#   'Authorization': 'Basic ' + base64.b64encode('admin:s3cr3t'),
#   'Accept': 'application/json'
# }
print(header2)
```
```

--------------------------------

### Chainable Path Builder (`__getattr__` / `_(name)`)

Source: https://context7.com/zmallen/pygraylog/llms.txt

Dynamically extends the internal URL path using attribute access or the `_(name)` escape hatch.

```APIDOC
## Chainable Path Builder — `__getattr__` / `_(name)`

Attribute access on a `GraylogAPI` instance dynamically extends the internal URL path, returning a new `GraylogAPI` instance with the appended segment. Python reserved words or names with special characters can be accessed via the `_(name)` escape hatch.

### Usage
Each attribute access appends a path segment.

### Request Example
```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900', username='admin', password='s3cr3t')

# Each attribute access appends a path segment
search_api = api.search          # path: /search
universal  = search_api.universal  # path: /search/universal
absolute   = universal.absolute    # path: /search/universal/absolute

# Using _(name) for reserved words or dynamic segment names
# e.g. api._('from') avoids Python's reserved keyword 'from'
print(absolute._path)  # /search/universal/absolute
```
```

--------------------------------

### Relative Time Range Search with pygraylog

Source: https://context7.com/zmallen/pygraylog/llms.txt

Perform searches within a rolling time window using search.universal.relative.get. Requires 'fields', 'query', and 'range' (in seconds). Suitable for real-time dashboards.

```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='xopqoiwepmd1o23m9awuaspofp')

# Search all messages in the last 5 minutes (300 seconds)
result = api.search.universal.relative.get(
    fields='message,src_ip,level',
    query='level:ERROR',
    range=300,
    limit=50      # optional
)
print(result)  # JSON string response from Graylog
```

--------------------------------

### Chainable Path Builder

Source: https://context7.com/zmallen/pygraylog/llms.txt

Dynamically build API URL paths using attribute access. Use the _(name) method for reserved keywords or special characters in path segments.

```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900', username='admin', password='s3cr3t')

# Each attribute access appends a path segment
search_api = api.search          # path: /search
universal  = search_api.universal  # path: /search/universal
absolute   = universal.absolute    # path: /search/universal/absolute

# Using _(name) for reserved words or dynamic segment names
# e.g. api._('from') avoids Python's reserved keyword 'from'
print(absolute._path)  # /search/universal/absolute
```

--------------------------------

### Absolute Time Range Search

Source: https://context7.com/zmallen/pygraylog/llms.txt

Perform a Graylog search within a specified date and time range. Requires 'fields', 'query', 'from_', and 'to' parameters. Optional parameters like 'limit' and 'offset' can be included.

```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900',
                 api_key='xopqoiwepmd1o23m9awuaspofp')

# Search all messages in a date window, returning the 'src_ip' field
result = api.search.universal.absolute.get(
    fields='src_ip',
    query='*',
    from_='2024-01-01 00:00:00',
    to='2024-01-01 23:59:59',
    limit=100,        # optional
    offset=0          # optional
)
print(result)  # JSON string response from Graylog
```

--------------------------------

### search.universal.relative.get

Source: https://context7.com/zmallen/pygraylog/llms.txt

Searches messages within a rolling window relative to now, defined in seconds via the `range` parameter. Required parameters are `fields`, `query`, and `range`. Suitable for real-time dashboards and alerting queries.

```APIDOC
## search.universal.relative.get

### Description
Searches messages within a rolling window relative to now, defined in seconds via the `range` parameter. Required parameters are `fields`, `query`, and `range`. Suitable for real-time dashboards and alerting queries.

### Method
GET

### Endpoint
/search/universal/relative

### Parameters
#### Query Parameters
- **fields** (string) - Required - Comma-separated list of fields to retrieve.
- **query** (string) - Required - The search query.
- **range** (integer) - Required - The time window in seconds relative to now.
- **limit** (integer) - Optional - Maximum number of messages to return.

### Request Example
```python
api.search.universal.relative.get(
    fields='message,src_ip,level',
    query='level:ERROR',
    range=300,
    limit=50
)
```

### Response
#### Success Response (200)
- **messages** (array) - A list of log message objects.
- **total_results** (integer) - The total number of messages matching the query within the range.

### Response Example
```json
{
  "messages": [
    {"message": "Error occurred", "src_ip": "10.0.0.1", "level": "ERROR"}
  ],
  "total_results": 10
}
```
```

--------------------------------

### call

Source: https://context7.com/zmallen/pygraylog/llms.txt

`call(method, **kwargs)` is the internal dispatcher invoked by `.get()`. It looks up required parameters for the current path in the `endpoints` registry, raises `ValueError` if any are missing, strips trailing underscores from argument names (e.g. `from_` → `from`), then delegates to `_get()`. It can also be called directly for advanced use cases.

```APIDOC
## call

### Description
`call(method, **kwargs)` is the internal dispatcher invoked by `.get()`. It looks up required parameters for the current path in the `endpoints` registry, raises `ValueError` if any are missing, strips trailing underscores from argument names (e.g. `from_` → `from`), then delegates to `_get()`. It can also be called directly for advanced use cases.

### Method
Internal Dispatcher (invoked via specific endpoint objects)

### Parameters
- **method** (string) - The HTTP method to call (e.g., 'get').
- **kwargs** (dict) - Keyword arguments representing parameters for the API call.

### Request Example
```python
endpoint = api.search.universal.relative
result = endpoint.call('get',
    fields='src_ip',
    query='*',
    range=600
)
```

### Response
#### Success Response (200)
- Varies based on the specific endpoint called.

### Response Example
```json
// Example response depends on the endpoint called via 'call'
```
```

--------------------------------

### Relative Time Range Term Aggregation with pygraylog

Source: https://context7.com/zmallen/pygraylog/llms.txt

Aggregate term frequencies over a relative time window using search.universal.relative.terms.get. Requires 'field', 'query', and 'range' (in seconds). Ideal for trend analysis.

```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900',
                 username='admin', password='s3cr3t')

# Top 'src_ip' values in the last hour (3600 seconds)
result = api.search.universal.relative.terms.get(
    field='src_ip',
    query='*',
    range=3600,
    size=20    # optional: number of top terms
)
print(result)  # JSON string with term counts
```

--------------------------------

### Direct HTTP Dispatch with call() in pygraylog

Source: https://context7.com/zmallen/pygraylog/llms.txt

Use the internal call() method for direct HTTP dispatch, bypassing the convenience wrappers like .get(). It handles parameter validation and argument name normalization (e.g., 'from_' to 'from').

```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900',
                 username='admin', password='s3cr3t')

# Equivalent to api.search.universal.relative.get(...)
endpoint = api.search.universal.relative
result = endpoint.call('get',
    fields='src_ip',
    query='*',
    range=600
)
print(result)
```

--------------------------------

### Perform Universal Search API Call

Source: https://github.com/zmallen/pygraylog/blob/master/README.md

Make an API call to search for messages using the universal search endpoint. You can specify fields, a query, and time range. Additional parameters like limit and offset can also be passed.

```python
api.search.universal.absolute.get(fields="src_ip", query="*", from_='1970-01-01 00:00:00', to='1970-01-01 23:59:59')
```

--------------------------------

### Absolute Time Range Term Aggregation with pygraylog

Source: https://context7.com/zmallen/pygraylog/llms.txt

Use search.universal.absolute.terms.get to count term occurrences for a specific field within a fixed date range. Requires 'field', 'query', 'from_', and 'to'.

```python
from pygraylog.graylogapi import GraylogAPI

api = GraylogAPI('https://graylog.example.com:12900',
                 username='admin', password='s3cr3t')

# Count occurrences of each unique 'src_ip' value over a day
result = api.search.universal.absolute.terms.get(
    field='src_ip',
    query='*',
    from_='2024-06-01 00:00:00',
    to='2024-06-01 23:59:59',
    size=10    # optional: max number of terms to return
)
print(result)  # JSON string with term frequency data
```

--------------------------------

### search.universal.relative.terms.get

Source: https://context7.com/zmallen/pygraylog/llms.txt

Aggregates term frequencies for a field over a relative time window. Required parameters are `field`, `query`, and `range`. Ideal for trend analysis or identifying top values over recent time windows.

```APIDOC
## search.universal.relative.terms.get

### Description
Aggregates term frequencies for a field over a relative time window. Required parameters are `field`, `query`, and `range`. Ideal for trend analysis or identifying top values over recent time windows.

### Method
GET

### Endpoint
/search/universal/relative/terms

### Parameters
#### Query Parameters
- **field** (string) - Required - The field to aggregate terms from.
- **query** (string) - Required - The search query.
- **range** (integer) - Required - The time window in seconds relative to now.
- **size** (integer) - Optional - Maximum number of terms to return.

### Request Example
```python
api.search.universal.relative.terms.get(
    field='src_ip',
    query='*',
    range=3600,
    size=20
)
```

### Response
#### Success Response (200)
- **terms** (array) - A list of term frequency objects.
- **message_count** (integer) - The total number of messages matching the query within the range.

### Response Example
```json
{
  "terms": [
    {"term": "10.0.0.1", "count": 50},
    {"term": "10.0.0.2", "count": 30}
  ],
  "message_count": 100
}
```
```

--------------------------------

### search.universal.absolute.terms.get

Source: https://context7.com/zmallen/pygraylog/llms.txt

Returns term frequency counts for a specific field within a fixed date range. Required parameters are `field` (singular), `query`, `from_`, and `to`. Useful for aggregating top values of a field (e.g. top source IPs) over a historical window.

```APIDOC
## search.universal.absolute.terms.get

### Description
Returns term frequency counts for a specific field within a fixed date range. Required parameters are `field` (singular), `query`, `from_`, and `to`. Useful for aggregating top values of a field (e.g. top source IPs) over a historical window.

### Method
GET

### Endpoint
/search/universal/absolute/terms

### Parameters
#### Query Parameters
- **field** (string) - Required - The field to aggregate terms from.
- **query** (string) - Required - The search query.
- **from_** (string) - Required - The start of the absolute time range (e.g., 'YYYY-MM-DD HH:MM:SS').
- **to** (string) - Required - The end of the absolute time range (e.g., 'YYYY-MM-DD HH:MM:SS').
- **size** (integer) - Optional - Maximum number of terms to return.

### Request Example
```python
api.search.universal.absolute.terms.get(
    field='src_ip',
    query='*',
    from_='2024-06-01 00:00:00',
    to='2024-06-01 23:59:59',
    size=10
)
```

### Response
#### Success Response (200)
- **terms** (array) - A list of term frequency objects.
- **message_count** (integer) - The total number of messages matching the query.

### Response Example
```json
{
  "terms": [
    {"term": "192.168.1.1", "count": 150},
    {"term": "192.168.1.2", "count": 100}
  ],
  "message_count": 500
}
```
```
Tokens:
Raw