name: graylog-tst description: > Graylog test environment specialist for log search, aggregation, and analysis. Use when asked to: search logs, find errors, query streams, analyze log patterns, investigate test run failures, debug staging issues, or check log volumes in the test or staging environment. Trigger keywords: graylog-tst. Do NOT use for production environment logs (use graylog-prd instead). compatibility: Requires graylog-tst agent (.codex/agents/graylog-tst.agent.md) and graylog-tst MCP server.

Graylog Test Environment Skill

Agent Delegation

Delegate ALL operations to the graylog-tst agent. "Use the graylog-tst agent to complete this task."

The graylog-tst agent provisions the graylog-tst MCP server and has the required tools (search_messages, aggregate_messages, list_streams, list_fields, etc.).

Description

Access Graylog test environment for log search, aggregation, and analysis. Use for development debugging, test run log investigation in test environment troubleshooting. Logs are organized into streams and stored in indices. Queries use Lucene syntax.

Capabilities

• Search test environment log messages using Lucene query syntax
• Aggregate logs (group by fields, count, avg, min, max, percentiles, etc.)
• List available streams and scope searches to specific streams
• List indices and index sets (data retention configuration)
• List configured inputs (syslog, GELF, etc.)
• Discover available fields per stream (list_fields) before querying
• Get current server time and system status

Key Concepts

• Streams: Named partitions of log data (e.g., by app, environment, source). Always scope searches to streams for performance.
• Indices: Physical storage units; use list_indices to check data availability and health.
• Fields: Field names vary per stream. Always call list_fields first to discover valid field names before building queries.
• Lucene syntax: Queries use Lucene (e.g., level:ERROR AND source:api-server). Leading wildcards are disabled by default.

Workflow

1. Connectivity check — call get_system_status as a lightweight probe. If it fails, stop and report: "graylog-tst MCP server is unavailable. Cannot proceed."
2. Discover streams — call list_streams to get stream IDs; always scope searches with the streams parameter.
3. Discover fields — call list_fields on the target stream before building any query.
4. Search or aggregate — use search_messages for raw logs, aggregate_messages for counts/grouping.
5. Report — structure the response as: time range → total hits → error/warn breakdown → top patterns → recommended actions.

Usage Examples

Log Search

graylog-tst Search for authentication errors in test environment last hour

Aggregate by Error Type

graylog-tst Show top 10 error types in staging grouped by source

Discover Fields First

graylog-tst List available fields in the staging application stream

Analyze Error Patterns

graylog-tst Analyze error patterns in test logs over the last 2 hours

Configuration

• Requires proper authentication via environment variable GRAYLOG_TST_TOKEN is defined in .codex/.env
• Do NOT search the filesystem for mcp-config.json — always route through the agent file

Best Practices

• Always call list_streams first to get stream IDs, then scope searches using the streams parameter
• Always call list_fields before querying to discover valid field names for the target stream
• Use aggregate_messages instead of search_messages for counting/grouping
• Pass time range as range_seconds parameter — never embed time in the query string
• Avoid leading wildcards in Lucene queries (disabled by default)

Limitations

• Test environment only — data does not reflect production
• Different data retention policies than production
• Leading wildcards are disabled in Lucene queries

Environment Isolation

CRITICAL: Never use graylog-tst and graylog-prd in the same request. Choose only one environment per query.