Humanlog

https://humanlog.io/docs
Admin
Humanlog is a developer-first observability platform for local exploration of logs and distributed...
Tokens:9,381
Snippets:170
Trust Score:5.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install humanlog via shell

Source: https://humanlog.io/docs/get-started/installation

Executes the installation script to add the binary to your PATH and start the background service.

```bash
curl -L "https://humanlog.io/install.sh" | bash
```

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

### Inspect Install Script

Source: https://humanlog.io/docs/features/cli

Fetches and displays the content of the Humanlog installation script for manual inspection. Useful for understanding the installation process.

```bash
curl -L "https://humanlog.io/install.sh" | cat

```

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

### Install Humanlog CLI

Source: https://humanlog.io/docs/features/cli

Installs the Humanlog CLI on your system and adds it to your shell's PATH. This is the primary installation command.

```bash
curl -sSL "https://humanlog.io/install.sh" | bash

```

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

### Spans Pipeline Example

Source: https://humanlog.io/docs/reference

An example of a pipeline starting with the 'spans' datasource, followed by a series of operators.

```humanlogql
spans | <operator_0> | <operator_1> | ... | <operator_N>
```

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

### Display version output example

Source: https://humanlog.io/docs/get-started/installation

Shows the expected output format when checking the version.

```text
humanlog version x.y.z
```

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

### Verify Humanlog Installation

Source: https://humanlog.io/docs/features/cli

Checks the installed version of the Humanlog CLI. This command is used to confirm that the installation was successful.

```bash
humanlog --version

```

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

### Start observability engine on Linux

Source: https://humanlog.io/docs/get-started/installation

Manually starts the local debugging environment on Linux systems where the service does not auto-start.

```bash
humanlog service run
```

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

### Verify humanlog installation

Source: https://humanlog.io/docs/get-started/installation

Checks the currently installed version of the humanlog binary.

```bash
humanlog --version
```

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

### Humanlog Query Example

Source: https://humanlog.io/docs/integrations/structured-logging

Use the `humanlog query` command to filter logs based on specific field values. This example filters for logs where the body contains 'getting auth URL'.

```bash
humanlog query 'filter body=="getting auth URL"'

```

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

### Run Humanlog as a Service (Linux)

Source: https://humanlog.io/docs/features/cli

Systemd service file configuration for running the Humanlog query engine as a background service on Linux. Ensure the ExecStart path is correct for your installation.

```systemd
[Unit]
Description=Humanlog Query Engine

[Service]
ExecStart=$HOME/.humanlog/bin/humanlog service run

[Install]
WantedBy=multi-user.target


```

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

### Example of Logfmt Log Entry

Source: https://humanlog.io/docs/integrations/structured-logging

Logfmt is a compact key-value format. Humanlog automatically parses this format, preserving all key-value pairs.

```logfmt
level=info ts=1591024000 msg="Request completed" method=GET path=/api/users status=200 duration_ms=42 user_id=abc123

```

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

### Example of Free-Form Text Log

Source: https://humanlog.io/docs/integrations/structured-logging

This is an example of a traditional, free-form text log line.

```text
2025-06-05 12:34:56 WARN User 123 failed to log in from IP 10.0.0.5

```

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

### Example of Structured JSON Log

Source: https://humanlog.io/docs/integrations/structured-logging

This is an example of a structured log entry formatted as JSON, with distinct fields for timestamp, level, message, and context.

```json
{"timestamp": "2025-06-05T12:34:56Z", "level": "WARN", "msg": "User failed to log in", "user_id": "123", "source_ip": "10.0.0.5"}

```

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

### Example of JSON Log Entry

Source: https://humanlog.io/docs/integrations/structured-logging

Humanlog can parse newline-separated JSON logs. Ensure your logs adhere to JSON formatting.

```json
{"level": "info", "ts": 1591024000, "msg": "Request completed", "method": "GET", "path": "/api/users", "status": 200, "duration_ms": 42, "user_id": "abc123"}

```

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

### Update Humanlog

Source: https://humanlog.io/docs/features/cli

Updates the Humanlog CLI to the latest available version. This command handles the download and installation of the new version.

```bash
humanlog version update

```

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

### Display OTLP configuration settings

Source: https://humanlog.io/docs/integrations/opentelemetry

Use this command to verify the current OTLP port configuration for the Humanlog service.

```bash
$ humanlog config show | jq '.runtime.experimental_features.serve_localhost.otlp'
{
  "grpc_port": 4317,
  "http_port": 4318
}
```

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

### Run a Query via CLI

Source: https://humanlog.io/docs/features/query

Execute a Humanlog query from the command line. This command opens the UI with the specified query pre-loaded and executed.

```bash
humanlog query 'filter true | take 10'
```

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

### Configure Humanlog settings

Source: https://humanlog.io/docs/features/cli

Commands to manage the Humanlog configuration file, including resetting, editing, and enabling/disabling features.

```bash
humanlog config reset-to-defaults
humanlog config edit
humanlog config show
humanlog config show-defaults
humanlog config enable
humanlog config disable
humanlog config hack
humanlog config hack for-netskope
```

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

### Stream Logs with Humanlog

Source: https://humanlog.io/docs/integrations/structured-logging

Use `tail -f` to stream logs in real-time and pipe them to humanlog for immediate processing and display.

```bash
tail -f application.log | humanlog

```

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

### Execute stream queries

Source: https://humanlog.io/docs/get-started/basic-usage

Run open-ended queries against incoming data in real time.

```bash
humanlog stream 'filter body == "something in the future that i'm looking forward to"'
```

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

### Prettify and query logs

Source: https://humanlog.io/docs/features/cli

Commands for piping application logs into Humanlog for formatting and executing complex queries.

```bash
my_app | humanlog
humanlog query 'filter len(body) > 10'
humanlog query 'summarize count() by severity_text'
humanlog query 'spans | where duration > 200ms | sample 10'
```

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

### Stream logs in real-time

Source: https://humanlog.io/docs/features/cli

Use the stream command to monitor logs matching specific criteria as they are emitted.

```bash
humanlog stream 'filter severity_text == "ERROR"'
```

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

### Basic Pipeline Structure

Source: https://humanlog.io/docs/reference

A query is structured as a series of pipeline operations separated by '|'. You can optionally specify a data source at the beginning.

```humanlogql
logs | <operator_0> | <operator_1> | ... | <operator_N>
```

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

### Ingest and query logs

Source: https://humanlog.io/docs/features/cli

Basic commands to ingest logs from files or streams and perform queries on the ingested data.

```bash
humanlog < logfile
humanlog query 'filter true'
```

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

### Pipeline Without Explicit Data Source

Source: https://humanlog.io/docs/reference

If no data source is specified, the query defaults to the 'logs' datasource.

```humanlogql
<operator_0> | <operator_1> | ... | <operator_N>
```

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

### View Container Logs with Humanlog

Source: https://humanlog.io/docs/integrations/structured-logging

Pipe the output of `docker logs` to humanlog to view and parse logs from Docker containers.

```bash
docker logs my-container | humanlog

```

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

### Stream Docker logs to humanlog

Source: https://humanlog.io/docs/integrations/containers

Use these commands to identify a container and pipe its logs directly into the humanlog utility.

```bash
# find the container to monitor
docker ps

# stream the logs into humanlog
docker logs 86e17ac9f03b | humanlog
```

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

### Basic Humanlog Usage

Source: https://humanlog.io/docs/integrations/structured-logging

Pipe log files into the humanlog command for instant parsing and colorization. This is the most basic way to view structured logs.

```bash
cat application.log | humanlog

```

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

### Ingest logs without output

Source: https://humanlog.io/docs/features/cli

Redirect standard output to /dev/null to perform ingestion without displaying prettified logs.

```bash
my_app | humanlog > /dev/null
```

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

### Ingest logs via CLI

Source: https://humanlog.io/docs/get-started/basic-usage

Pipe application output or file content into the Humanlog CLI to prettify and ingest logs.

```bash
my_app | humanlog
```

```bash
humanlog < your_log_file
```

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

### Check for Humanlog Updates

Source: https://humanlog.io/docs/features/cli

Checks if a new version of Humanlog is available. This command queries the update server to see if a newer release exists.

```bash
humanlog version check

```

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

### Empty Query Equivalent

Source: https://humanlog.io/docs/reference

An empty query is functionally equivalent to querying the 'logs' datasource with a filter that always evaluates to true.

```humanlogql
// no query
```

```humanlogql
// functional equivalent
logs | filter true
```

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

### Query historical data

Source: https://humanlog.io/docs/get-started/basic-usage

Execute point-in-time queries against ingested data via the CLI.

```bash
humanlog query 'filter request_id == "2937400f-b5c5-426f-b07a-4c7723ff6740"'
```

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

### Find Logs by Request ID

Source: https://humanlog.io/docs/reference

Use this query to filter log entries that match a specific request ID. Replace `<some_uuid>` with the actual request ID you are searching for.

```humanlog
where request_id == "<some_uuid>"
```

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

### Project Statement

Source: https://humanlog.io/docs/reference/operators/tabular

The project statement selects which fields to include in the output. It can also include computed columns and rename fields.

```APIDOC
## Project Statement

### Description
Selects which fields to include in the output.

### Details
- Only the specified fields will appear in the output
- Can include computed columns with field assignment
- Useful for reducing dataset size and focusing on relevant fields
- Can rename fields using the 'as' keyword

### Examples
- `datetime_part(part, _time)`: Extract all available parts from a timestamp.
- `top by kv desc renamed`
- `+` numerical operator (timestamps and durations)
- `>` greater than
- `>=` greater than or equal
- `<` less than
- `<=` less than or equal
- `and` logical operator
- `or` logical operator
- `+` numerical operator (f64)
- `+` numerical operator (i64)
- `-` numerical operator (f64)
- `-` numerical operator (i64)
- `-` numerical operator (timestamps and durations)
- `/` numerical operator (f64)
- `/` numerical operator (i64)
- `*` numerical operator (f64)
- `*` numerical operator (i64)
- `!` logical negation
- `-` numerical negation of literals
- `now()`: Current timestamp.
- `ago(x)`: Timestamp of `now() - 'x'`.
- String length
- `ceiling(x)`: Ceiling of an integer or floating-point number.
- `floor(x)`: Floor of an integer or floating-point number.
- `pi`: Returns the value of Pi (π).
- `log(x)`: Natural logarithm of a literal value or a referenced field.
- `log10(x)`: Common (base-10) logarithm of a numeric literal or referenced field.
- `log2(x)`: Base-2 logarithm of a numeric literal or referenced field.
- `gamma(x)`: Gamma function of a numeric literal or referenced field.
- `loggamma(x)`: Log-gamma function of a numeric literal or referenced field.
- `round(x)`: Rounds a numeric literal or referenced field to the nearest integer.
- `round(x, y)`: Rounds a floating-point number 'x' with 'y' decimals, or an integer 'x' with 'y' decimals.
- `pow(x, y)`: Returns 'x' raised to the power 'y'.
- `abs(x)`: Returns the absolute value of 'x'.
- `sqrt(x)`: Returns the square root of 'x'.
- `sign(x)`: Returns the sign of 'x'.
- `radians(x)`: Converts 'x' degrees to radians.
- `degrees(x)`: Converts 'x' radians to degrees.
- `sin(x)`: Returns the sine of 'x'.
- `asin(x)`: Returns the arcsine of 'x'.
- `cos(x)`: Returns the cosine of 'x'.
- `acos(x)`: Returns the arccosine of 'x'.
- `tan(x)`: Returns the tangent of 'x'.
```

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

### Filter Logs by Non-Empty Message

Source: https://humanlog.io/docs/reference

Use this query to find all log entries that have a message body.

```humanlog
logs | filter body != ""
```

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

### Configure color output

Source: https://humanlog.io/docs/features/cli

Control terminal color output when embedding Humanlog in scripts or CI pipelines.

```bash
my_command | humanlog --color=off
my_command | humanlog --color=on
my_command | humanlog --color=dark
my_command | humanlog --color=light
```

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

### Stream OpenTelemetry spans

Source: https://humanlog.io/docs/get-started/basic-usage

Monitor real-time spans being ingested into Humanlog using the stream command.

```bash
humanlog stream 'spans | filter true'
```

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

### Ingest logs without prettifying

Source: https://humanlog.io/docs/get-started/basic-usage

Use the ingest command to process logs silently without printing them to the terminal.

```bash
# ingest logs from an app, without printing them
my_app | humanlog ingest

# ingest logs from a file, without printing them
humanlog ingest < your_log_file
```

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

### Summarize Statement

Source: https://humanlog.io/docs/reference/operators/tabular

The summarize statement calculates aggregate values over groups of log entries. It supports multiple aggregation functions and an optional 'by' clause for grouping.

```APIDOC
## Summarize Statement

### Description
Calculates aggregate values over groups of log entries.

### Details
- Supports multiple aggregation functions: count(), sum(), avg(), min(), max()
- Can compute multiple aggregations in a single statement
- Optional 'by' clause groups results by specified fields
- Commonly used with time-based binning for timeseries analysis

### Examples
- Daily histogram of total event counts per minute
- Summarize dcount
- Summarize histogram
- Summarize percentile if value lt
- Summarize percentile
- Summarize stddev if value lt
- Summarize stddev
- Summarize variance if value lt
- Summarize variance
- Summarize count if value lt
- Summarize dcount if value lt
- Summarize dcount
- Summarize sum if value lt
- Summarize sum
- Summarize min if value lt
- Summarize min
- Summarize max if value lt
- Summarize max
- Summarize average if value gt
- Summarize average (integer becomes float)
- Refer to summarized column
- Refer to summarized column, sort desc
- Refer to summarized column, sort asc
- Summarize by _time
- Summarize by binned _time
```

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

### Query Spans

Source: https://humanlog.io/docs/features/query

Retrieve a specified number of spans from tracing data to debug distributed systems.

```text
spans | take 10

```

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

### Filter by Request ID

Source: https://humanlog.io/docs/features/query

Filter logs based on a specific request ID. The `request_id` symbol can be referenced directly.

```humanlog
// `request_id` is a symbol found in the key-values of your logs
filter request_id == "2937400f-b5c5-426f-b07a-4c7723ff6740"
```

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

### Filter by Build Commit with Escaped Symbol

Source: https://humanlog.io/docs/features/query

Filter logs using a symbol that contains special characters like a period. Such symbols must be enclosed in single or double quotes and referenced as an index expression.

```humanlog
// `build.Commit` is a symbol found in the key-values of your logs
// it contains a `.` so it must be escaped.
filter ['build.Commit'] == "d31fade"
```

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

### Find Trace IDs with Most Spans

Source: https://humanlog.io/docs/reference

This query identifies trace IDs that have the highest number of spans in the last hour. It filters spans by time, summarizes the count of spans per trace ID, and then sorts the results in descending order.

```humanlog
spans
| filter _time > ago(1h)
| summarize span_count=count() by trace_id
| sort by span_count desc
```

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

### Count Spans in the Last Hour

Source: https://humanlog.io/docs/reference

This query counts the number of spans recorded within the last hour. It uses the `ago` function for time-based filtering and `summarize count()` for aggregation.

```humanlog
spans | where _time > ago(1h) | summarize count()
```
Tokens:
Raw