Skip to main content

Redis and Valkey Setup

Logstag monitors Redis and Valkey through the Redis protocol. The same monitoring model is used for both engines because Valkey is Redis protocol compatible.

Use a dedicated monitoring user when ACLs are enabled. The user needs read-only operational visibility and should remain separate from application access.

Supported Deployment Scope​

AreaSupport
RedisRedis 7.0 and later.
ValkeyValkey 8.0 and later.
StandaloneSupported.
ReplicationSupported for primary and replica role visibility.
Redis ClusterRequires separate deployment validation.
SentinelRequires separate deployment validation.

For clustered Redis or Sentinel environments, monitor each supported Redis or Valkey node according to the deployment guidance approved for that environment.

Redis Target Configuration​

Add a Redis target entry to the agent configuration.

[targets.production-redis]
platform = "self-hosted"
db_engine = "redis"
db_host = "redis.example.internal"
db_port = 6379
db_username = "logstag_monitor"
db_password = "<your-database-password>"
db_name = "0"

For Redis and Valkey, db_name is the logical database number as a string. Use a value from 0 to 15 unless your environment has a different approved database layout.

Valkey Target Configuration​

Add a Valkey target entry with the same field model.

[targets.production-valkey]
platform = "self-hosted"
db_engine = "valkey"
db_host = "valkey.example.internal"
db_port = 6379
db_username = "logstag_monitor"
db_password = "<your-database-password>"
db_name = "0"

If the deployment is configured without authentication, db_username and db_password can be left empty. This should be limited to controlled development environments.

Access Model​

Access areaRequired for
PINGAgent health checks.
SELECTSelecting the configured logical database.
INFOServer, client, keyspace, memory, command, persistence, CPU, and replication metrics.
DBSIZEKey count for the monitored logical database.
ROLEPrimary or replica role detection.
CLIENT LISTClient connection metadata.
MEMORY STATSDetailed memory and allocator metadata.
SLOWLOG LEN and SLOWLOG GETSlow command monitoring.
LATENCY LATESTRedis latency event metadata.
CONFIG GETConfiguration monitoring and drift detection.
ACL USERS and ACL GETUSEROptional ACL and security inventory.

The minimum useful monitoring account needs PING, SELECT, INFO, DBSIZE, and ROLE. The remaining commands improve coverage but should be granted according to the monitoring scope you want Logstag to report.

Create a Monitoring User​

In Redis 6.0 and later, create or update an ACL user for monitoring.

ACL SETUSER logstag_monitor on >strong-password ~* &* \
  +ping +select +info +dbsize +role

This gives the user the core command visibility needed for health checks, database selection, server metrics, key count, and role detection.

For fuller operational coverage, add the read-only diagnostic commands required by your monitoring scope.

ACL SETUSER logstag_monitor \
  +client|list \
  +memory|stats \
  +slowlog|get +slowlog|len \
  +latency|latest \
  +config|get

If Logstag should collect ACL security inventory, grant ACL read visibility as a separate decision.

ACL SETUSER logstag_monitor +acl|users +acl|getuser

Keep write and destructive commands out of the monitoring user's ACL.

Password-Only Authentication​

Some Redis deployments use password-only authentication instead of named ACL users. In that case, leave db_username empty and set db_password.

[targets.production-redis]
platform = "self-hosted"
db_engine = "redis"
db_host = "redis.example.internal"
db_port = 6379
db_username = ""
db_password = "<your-database-password>"
db_name = "0"

Use named ACL users when the Redis version and security policy allow it. Named users make monitoring access easier to audit and rotate.

Data Collected​

Depending on enabled collectors and granted visibility, Logstag can collect:

  • Server runtime metrics, command throughput, network counters, keyspace hits and misses, evicted keys, expired keys, connected clients, blocked clients, and uptime.
  • Logical database key counts and key expiration counts for the configured database.
  • Client connection metadata, including client identifiers, address metadata, client names, idle time, selected database, subscriptions, buffer sizes, and last command names.
  • Replication role, connected replicas, replication offsets, backlog metadata, primary link state, and replica sync state.
  • Memory usage, memory limits, fragmentation, allocator metadata, Lua or script memory, and active defragmentation state where exposed.
  • Per-command usage counters, rejected calls, failed calls, and command CPU time.
  • Slow log summary and recent slow log entries, including command names, arguments, duration, timestamp, client address, and client name where Redis exposes them.
  • Latency event metadata for Redis latency spikes.
  • Persistence status for RDB and AOF, including save status, rewrite state, copy-on-write memory, pending operations, and persistence file size signals.
  • CPU counters for Redis server and background processes.
  • Configuration parameters and configuration drift indicators when CONFIG GET is permitted.
  • ACL user metadata, command permissions, key patterns, channel patterns, selectors, and privilege summaries when ACL read visibility is permitted.

Logstag does not read Redis key values as dataset content. Some Redis metadata can still be sensitive: key patterns, client addresses, client names, command arguments in slow logs, ACL rules, bind addresses, file names, and configuration parameters should be treated as operational metadata.

Deployment Notes​

Standalone Redis and Valkey instances may not expose meaningful replication metrics. Replication metrics are collected only when the node reports a primary or replica role.

Redis Cluster and Sentinel deployments require separate validation before rollout. This setup page describes standalone Redis and Valkey node monitoring.

Managed Redis services may restrict commands such as CONFIG GET, SLOWLOG, LATENCY, CLIENT LIST, or ACL inspection. When a command is restricted, Logstag can continue collecting the remaining permitted metrics and report reduced coverage for the restricted area.

Validate Setup​

After updating the target configuration, validate the agent configuration before restarting the service.

logstag-agent --config /etc/logstag-agent/config.toml --check-config

Restart the agent after validation.

sudo systemctl restart logstag-agent
sudo systemctl status logstag-agent

On Windows, restart the Logstag Agent service from the Services console or with the approved service management command used in your environment.

Troubleshooting​

SymptomCheck
Connection failsConfirm host, port, password or ACL credentials, firewall rules, TLS policy, and Redis authentication settings.
Database selection failsConfirm db_name is a valid logical database number and the user can run SELECT.
Server metrics are missingConfirm the user can run INFO.
Key count metrics are missingConfirm the user can select the configured database and run DBSIZE.
Replication metrics are missingConfirm the target is primary or replica and the user can run ROLE and read replication information.
Client metrics are missingConfirm CLIENT LIST is permitted.
Slow log metrics are missingConfirm SLOWLOG LEN and SLOWLOG GET are permitted.
Configuration metrics are missingConfirm CONFIG GET is permitted by ACL and provider policy.
Security inventory is missingConfirm ACL read visibility is intentionally granted. If not granted, this area is expected to be unavailable.
No metrics arrive after configuration changesValidate the configuration, restart the agent, and review local agent logs.