Logging Configuration

Gate uses structured logging with Uber’s Zap logger, providing high-performance, leveled logging with structured fields. Logs can be configured via command-line flags and environment variables.

Log Levels

Gate supports multiple log verbosity levels, controlled by the --verbosity flag or GATE_VERBOSITY environment variable:

Verbosity	Level	Use Case
`0`	Info	Production (default) - Essential operational messages
`1`	Debug	Development - Detailed debugging information
`2+`	Trace	Deep debugging - Very detailed internal operations

Setting Log Level

# Via command-line flag
gate --verbosity 1

# Via environment variable
export GATE_VERBOSITY=1
gate

# Enable debug mode (sets highest verbosity)
gate --debug
export GATE_DEBUG=true

Configuration

Command-Line Flags

# Verbosity control
gate --verbosity 2         # Set specific verbosity level
gate -v 2                  # Short form

# Debug mode (maximum verbosity)
gate --debug               # Enable debug logging
gate -d                    # Short form

# Show version
gate --version             # Display version and exit
gate -V                    # Short form (Unix convention)

Environment Variables

export GATE_VERBOSITY=1    # Set verbosity level
export GATE_DEBUG=true     # Enable debug mode
export GATE_CONFIG="/path/to/config.yml"  # Config file location

Configuration File

# config.yml
config:
  debug: false  # Enable debug mode

Log Format

Gate uses different log formats depending on the mode:

Production Format (Default)

JSON-structured logs optimized for machine parsing:

{
  "level": "info",
  "ts": "2024-03-04T10:30:45.123Z",
  "logger": "gate",
  "msg": "starting Gate proxy",
  "version": "v0.28.0"
}

Development Format (Debug Mode)

Human-readable console logs with colors:

2024-03-04T10:30:45.123Z  INFO  gate  starting Gate proxy  {"version": "v0.28.0"}

Logger Implementation

Gate’s logger is configured in cmd/gate/root.go:191:

func newLogger(debug bool, v int) (l logr.Logger, err error) {
    var cfg zap.Config
    if debug {
        cfg = zap.NewDevelopmentConfig()
    } else {
        cfg = zap.NewProductionConfig()
    }
    cfg.Level = zap.NewAtomicLevelAt(zapcore.Level(-v))
    
    cfg.Encoding = "console"
    cfg.EncoderConfig.EncodeLevel = zapcore.CapitalColorLevelEncoder
    cfg.EncoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
    
    zl, err := cfg.Build()
    if err != nil {
        return logr.Discard(), err
    }
    
    return zapr.NewLogger(zl), nil
}

Structured Fields

Gate logs include structured fields for easy filtering:

log.Info("player connected", 
    "username", player.Name,
    "uuid", player.UUID,
    "address", conn.RemoteAddr(),
)

Output:

{
  "level": "info",
  "msg": "player connected",
  "username": "Notch",
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "address": "192.168.1.100:54321"
}

OpenTelemetry Integration

When OpenTelemetry tracing is enabled, logs automatically include trace context:

export OTEL_TRACES_ENABLED="true"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"

Logs will include trace and span IDs:

{
  "level": "info",
  "msg": "processing packet",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "span_id": "00f067aa0ba902b7"
}

This enables correlation between logs and traces in observability platforms.

Log Aggregation

Grafana Loki

Loki is designed for aggregating logs from multiple sources.

Docker Compose with Loki

services:
  gate:
    image: ghcr.io/minekube/gate:latest
    environment:
      - GATE_VERBOSITY=1
    logging:
      driver: loki
      options:
        loki-url: "http://localhost:3100/loki/api/v1/push"
        loki-external-labels: "service=gate,environment=production"
    networks:
      - logging

  loki:
    image: grafana/loki:latest
    command: -config.file=/etc/loki/local-config.yaml
    ports:
      - "3100:3100"
    networks:
      - logging

  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_AUTH_ANONYMOUS_ENABLED=true
      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
    volumes:
      - ./grafana-datasources.yml:/etc/grafana/provisioning/datasources/datasources.yaml
    ports:
      - "3000:3000"
    networks:
      - logging

networks:
  logging:

Loki Configuration

# grafana-datasources.yml
apiVersion: 1

datasources:
  - name: Loki
    type: loki
    access: proxy
    url: http://loki:3100
    isDefault: true

Querying Logs in Grafana

# All Gate logs
{service="gate"}

# Error logs only
{service="gate"} |= "level=error"

# Player connection logs
{service="gate"} |= "player connected"

# Logs for specific player
{service="gate"} | json | username="Notch"

# Logs with trace ID
{service="gate"} | json | trace_id=~".+"

Promtail for Log Shipping

Use Promtail to ship logs from files to Loki:

# promtail-config.yml
server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: gate
    static_configs:
      - targets:
          - localhost
        labels:
          job: gate
          __path__: /var/log/gate/*.log

Elasticsearch and Kibana

For Elasticsearch-based log aggregation:

services:
  gate:
    image: ghcr.io/minekube/gate:latest
    environment:
      - GATE_VERBOSITY=1
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  filebeat:
    image: docker.elastic.co/beats/filebeat:8.10.0
    user: root
    volumes:
      - ./filebeat.yml:/usr/share/filebeat/filebeat.yml:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.10.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"

  kibana:
    image: docker.elastic.co/kibana/kibana:8.10.0
    ports:
      - "5601:5601"
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200

Best Practices

1. Production Logging

# Production: Info level, JSON format
export GATE_VERBOSITY=0
export GATE_DEBUG=false

Log only essential information:

Service startup/shutdown
Player connections/disconnections
Configuration changes
Errors and warnings

2. Development Logging

# Development: Debug level, console format
gate --debug --verbosity 2

Includes:

Detailed packet information
Authentication flows
Internal state changes
Performance metrics

3. Structured Fields

Always use structured fields instead of string formatting:

// Good - Structured
log.Info("player joined",
    "player", player.Name,
    "server", server.Name,
    "time", time.Now(),
)

// Bad - String formatting
log.Info(fmt.Sprintf("Player %s joined server %s", player.Name, server.Name))

4. Log Sampling

For high-frequency events, use sampling to reduce log volume:

// Log only 10% of packet events
if rand.Float64() < 0.1 {
    log.V(1).Info("packet received", "type", packet.Type)
}

5. Sensitive Data

Never log sensitive information:

// Bad - Logs sensitive data
log.Info("auth token", "token", authToken)

// Good - Redacted
log.Info("auth token", "token", "<redacted>")

6. Error Context

Include context when logging errors:

if err := connectToServer(server); err != nil {
    log.Error(err, "failed to connect to server",
        "server", server.Name,
        "attempt", retryCount,
        "max_retries", maxRetries,
    )
}

Log Rotation

Using logrotate (Linux)

# /etc/logrotate.d/gate
/var/log/gate/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 gate gate
    sharedscripts
    postrotate
        systemctl reload gate || true
    endscript
}

Using Docker logging driver

services:
  gate:
    image: ghcr.io/minekube/gate:latest
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
        compress: "true"

Custom Plugin Logging

Use the context logger in your plugins:

import (
    "context"
    "github.com/go-logr/logr"
)

func MyPluginInit(ctx context.Context) error {
    log := logr.FromContextOrDiscard(ctx).WithName("my-plugin")
    
    log.Info("plugin initialized", "version", "1.0.0")
    
    // Debug logging (only shown at verbosity >= 1)
    log.V(1).Info("debug information", "detail", "value")
    
    // Error logging
    if err := doSomething(); err != nil {
        log.Error(err, "operation failed", "context", "additional info")
    }
    
    return nil
}

Troubleshooting

No Logs Appearing

Check verbosity level:
```
echo $GATE_VERBOSITY
```

Ensure debug mode is not disabled in config:

config:
  debug: true  # Enable for development

Verify logger initialization in Gate startup logs

Too Many Logs

Reduce verbosity:
```
export GATE_VERBOSITY=0
```
Disable debug mode:
```
unset GATE_DEBUG
```
Implement log sampling for high-frequency events

Logs Not in JSON Format

Gate uses console encoding by default. For JSON logs, you need to modify the logger configuration or use a log shipper to parse console logs.

Logging Configuration

Logging Configuration

Log Levels

Setting Log Level

Configuration

Command-Line Flags

Environment Variables

Configuration File

Log Format

Production Format (Default)

Development Format (Debug Mode)

Logger Implementation

Structured Fields

OpenTelemetry Integration

Log Aggregation

Grafana Loki

Docker Compose with Loki

Loki Configuration

Querying Logs in Grafana

Promtail for Log Shipping

Elasticsearch and Kibana

Best Practices

1. Production Logging

2. Development Logging

3. Structured Fields

4. Log Sampling

5. Sensitive Data

6. Error Context

Log Rotation

Using logrotate (Linux)

Using Docker logging driver

Custom Plugin Logging

Troubleshooting

No Logs Appearing

Too Many Logs

Logs Not in JSON Format

Next Steps

OpenTelemetry

Metrics

Documentation Index

​Logging Configuration

​Log Levels

​Setting Log Level

​Configuration

​Command-Line Flags

​Environment Variables

​Configuration File

​Log Format

​Production Format (Default)

​Development Format (Debug Mode)

​Logger Implementation

​Structured Fields

​OpenTelemetry Integration

​Log Aggregation

​Grafana Loki

​Docker Compose with Loki

​Loki Configuration

​Querying Logs in Grafana

​Promtail for Log Shipping

​Elasticsearch and Kibana

​Best Practices

​1. Production Logging

​2. Development Logging

​3. Structured Fields

​4. Log Sampling

​5. Sensitive Data

​6. Error Context

​Log Rotation

​Using logrotate (Linux)

​Using Docker logging driver

​Custom Plugin Logging

​Troubleshooting

​No Logs Appearing

​Too Many Logs

​Logs Not in JSON Format

​Next Steps

OpenTelemetry

Metrics

Logging Configuration

Log Levels

Setting Log Level

Configuration

Command-Line Flags

Environment Variables

Configuration File

Log Format

Production Format (Default)

Development Format (Debug Mode)

Logger Implementation

Structured Fields

OpenTelemetry Integration

Log Aggregation

Grafana Loki

Docker Compose with Loki

Loki Configuration

Querying Logs in Grafana

Promtail for Log Shipping

Elasticsearch and Kibana

Best Practices

1. Production Logging

2. Development Logging

3. Structured Fields

4. Log Sampling

5. Sensitive Data

6. Error Context

Log Rotation

Using logrotate (Linux)

Using Docker logging driver

Custom Plugin Logging

Troubleshooting

No Logs Appearing

Too Many Logs

Logs Not in JSON Format

Next Steps