LogZilla Query Command Basics

The logzilla query command provides powerful programmatic access to LogZilla data through structured queries. This tool enables administrators to generate reports, extract specific data sets, and automate data analysis workflows.

Getting Started

Prerequisites

The query command requires authentication and proper permissions:

bash
Wrap: OnCopyFullscreen
# Ensure you have root access or appropriate permissions
sudo su -

# Create API token for authentication
logzilla authtoken create --user admin

Basic Command Structure

bash
Wrap: OnCopyFullscreen
logzilla query --type <QueryType> --params <parameters-file> [options]

Required Parameters:

• --type: Specifies the query type (Search, TopN, EventRate, etc.)
• --params: Path to JSON file containing query parameters

Common Options:

• --authtoken: API authentication token
• --user / --password: Username/password authentication
• --output-file: Save results to file
• --format: Output format (json, xlsx)

Authentication Setup

Method 1: API Token (Recommended)

bash
Wrap: OnCopyFullscreen
# Create token and save to environment
TOKEN=$(logzilla authtoken create --user admin --output json | jq -r '.token')
export LOGZILLA_API_KEY="$TOKEN"

# Use in queries
logzilla query --type Search --params search.json --authtoken $LOGZILLA_API_KEY

Method 2: Configuration File

Create ~/.lz5query configuration file:

ini
Wrap: OnCopyFullscreen
[lz5query]
authtoken = your-api-token-here
base_url = http://localhost/api

Method 3: Username/Password

bash
Wrap: OnCopyFullscreen
# Interactive password prompt
logzilla query --type Search --params search.json --user admin --password

# Direct password (less secure)
logzilla query --type Search --params search.json --user admin --password mypass

Core Query Types

Search Query

Retrieve specific events matching filter criteria. Most flexible query type for detailed event analysis.

Parameters File (search-params.json):

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "preset": "last_24_hours"
  },
  "filter": [
    {
      "field": "severity",
      "op": "le",
      "value": [3]
    }
  ],
  "limit": 100,
  "sort": ["-first_occurrence"]
}

Execute Query:

bash
Wrap: OnCopyFullscreen
logzilla query --type Search --params search-params.json --authtoken $TOKEN

TopN Query

Find the most frequent values for a specific field. Ideal for identifying top talkers, most active hosts, or common error patterns.

Parameters File (topn-params.json):

json
Wrap: OnCopyFullscreen
{
  "field": "host",
  "limit": 10,
  "time_range": {
    "preset": "last_7_days"
  },
  "filter": [
    {
      "field": "program",
      "op": "eq",
      "value": ["sshd"]
    }
  ]
}

Execute Query:

bash
Wrap: OnCopyFullscreen
logzilla query --type TopN --params topn-params.json --authtoken $TOKEN

EventRate Query

Calculate event rates over time periods. Useful for trend analysis and capacity planning.

Parameters File (eventrate-params.json):

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "preset": "last_24_hours",
    "step": 3600
  },
  "filter": [
    {
      "field": "severity",
      "op": "le",
      "value": [4]
    }
  ]
}

Execute Query:

bash
Wrap: OnCopyFullscreen
logzilla query --type EventRate --params eventrate-params.json --authtoken $TOKEN

Common Parameters

Time Range Configuration

Time ranges define the period for data retrieval. Multiple formats supported:

Preset Time Ranges

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "preset": "today"
  }
}

Available Presets:

• today - Current day from midnight
• yesterday - Previous day
• last_1_hours - Last 1 hour
• last_24_hours - Last 24 hours
• last_7_days - Last 7 days
• last_30_days - Last 30 days
• last_365_days - Last 365 days

Note: Dynamic presets are supported with the pattern last_N_unit, where unit is one of seconds, minutes, hours, days, or weeks. Examples:

• last_6_hours
• last_12_hours
• last_90_days
• last_2_weeks

Absolute Time Ranges

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "ts_from": "2024-01-01 00:00:00",
    "ts_to": "2024-01-31 23:59:59"
  }
}

Unix Timestamps

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "ts_from": 1704067200,
    "ts_to": 1706745600
  }
}

Time Steps for Aggregation

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "preset": "last_24_hours",
    "step": 3600
  }
}

Common Step Values:

• 60 - 1 minute intervals
• 900 - 15 minute intervals
• 3600 - 1 hour intervals
• 86400 - 1 day intervals

Filter Configuration

Filters limit query results to specific criteria. Multiple filters are combined with AND logic.

Basic Filter Structure

json
Wrap: OnCopyFullscreen
{
  "filter": [
    {
      "field": "field_name",
      "op": "operator",
      "value": ["value1", "value2"]
    }
  ]
}

Available Operators

Filter Examples

Host Filter:

json
Wrap: OnCopyFullscreen
{
  "field": "host",
  "op": "eq",
  "value": ["web-server-01", "web-server-02"]
}

Severity Filter:

json
Wrap: OnCopyFullscreen
{
  "field": "severity",
  "op": "le",
  "value": [3]
}

Message Search:

json
Wrap: OnCopyFullscreen
{
  "field": "message",
  "op": "qp",
  "value": ["authentication failed"]
}

Wildcard Program Filter:

json
Wrap: OnCopyFullscreen
{
  "field": "program",
  "op": "=*",
  "value": ["ssh*"]
}

Archive Data Access

Include archived data in queries using the with_archive parameter:

json
Wrap: OnCopyFullscreen
{
  "time_range": {
    "preset": "last_365_days"
  },
  "with_archive": true,
  "filter": [
    {
      "field": "host",
      "op": "eq", 
      "value": ["critical-server"]
    }
  ]
}

Note: Queries with with_archive: true may take longer to execute as they search both active and archived data.

Result Limiting and Sorting

Limit Results

json
Wrap: OnCopyFullscreen
{
  "limit": 50,
  "page_size": 25
}

Sort Results

json
Wrap: OnCopyFullscreen
{
  "sort": ["-first_occurrence", "host"]
}

Sort Fields:

• first_occurrence / -first_occurrence (descending)
• last_occurrence / -last_occurrence (descending)
• count / -count (descending)
• host, program, severity

Output Formats

JSON Output (Default)

bash
Wrap: OnCopyFullscreen
logzilla query --type Search --params search.json --output results.json

Results saved as structured JSON for programmatic processing.

Excel Output

bash
Wrap: OnCopyFullscreen
logzilla query --type TopN --params topn.json --output report.xlsx --format xlsx

Results formatted as Excel spreadsheet for business reporting.

Console Output

bash
Wrap: OnCopyFullscreen
logzilla query --type Search --params search.json

Results displayed directly in terminal for immediate review.

Common Field Names

Standard Event Fields

Enhanced Fields

Error Handling

Common Issues

Authentication Errors:

bash
Wrap: OnCopyFullscreen
# Error: Invalid token
# Solution: Create new token
logzilla authtoken create --user admin

Parameter Errors:

bash
Wrap: OnCopyFullscreen
# Error: Invalid JSON in parameters file
# Solution: Validate JSON syntax
cat params.json | jq .

Time Range Errors:

bash
Wrap: OnCopyFullscreen
# Error: Invalid time range
# Solution: Check date format and range validity

Debugging

bash
Wrap: OnCopyFullscreen
# Enable debug output
logzilla query --type Search --params search.json --debug

# Validate parameters file
cat search.json | jq .

# Test with minimal parameters
echo '{"time_range": {"preset": "last_1_hours"}}' > test.json
logzilla query --type Search --params test.json

Troubleshooting

Verify that the ~/.lz5query file is correct and contains the correct credentials.

ini
Wrap: OnCopyFullscreen
[lz5query]
authtoken = your-api-token-here
base_url = http://localhost/api

Best Practices

Performance

• Use specific time ranges to limit data processing
• Apply filters to reduce result set size
• Use appropriate limits for large datasets
• Consider archived data impact on query performance

Security

• Use API tokens instead of passwords
• Protect configuration files with proper permissions
• Rotate tokens regularly for security
• Limit token permissions to required operations

Automation

• Validate JSON parameters before execution
• Handle errors gracefully in scripts
• Log query execution for audit trails
• Use consistent naming for parameter files

The query command provides the foundation for data analysis and reporting. Master these basics before moving to advanced query types and complex automation scenarios.