izle Service

🇹🇷 Türkçe Versiyonu | 🇬🇧 English Version

A monitoring service for periodically checking the status of hosts (Ping), HTTP endpoints, TCP ports, and TLS/SSL certificates. It supports JSON logging, Docker integration, and flexible YAML configuration.

Features

• Ping Check: Sends ICMP Echo Requests to target hosts. It runs in unprivileged mode, so it does not require root permissions.
• HTTP/HTTPS Check: Monitors HTTP/HTTPS endpoints and retrieves status codes.
• TCP Check: Checks if TCP ports are reachable and measures connection time.
• TLS/SSL Check: Monitors TLS/SSL certificate expiration dates and certificate details.
• Parallel Monitoring: All services (ping, HTTP, TCP, TLS) run in parallel based on the configuration file.
• Flexible Configuration: Manage all settings via a YAML configuration file.
• JSON Logging: Outputs logs in JSON format for easy parsing and integration with logging systems (e.g., Grafana Loki, ELK, Splunk).
• Docker Ready: Includes a multi-stage Dockerfile for easy deployment.

Data Pipeline Architecture

The logs produced by izle are in JSON format, making them easy to integrate with modern log aggregation and visualization tools. A typical data pipeline for izle would be:

izle -> Loki -> Grafana

1. izle: Generates structured JSON logs for every check (ping, HTTP, TCP, or TLS).
2. Loki: A log aggregation system from Grafana that is cost-effective and easy to operate. It indexes metadata about your logs, not the full text, which makes it very efficient.
3. Grafana: A visualization tool that can query Loki and display the data in dashboards, create alerts, and explore logs interactively.

This setup provides a powerful and scalable monitoring solution.

Configuration

izle requires a YAML configuration file to run. All monitoring services are configured in a single file:

• Ping configuration (ping: section)
• HTTP configuration (http: section)
• TCP configuration (tcp: section)
• TLS configuration (tls: section)

If a service has no targets configured, it is automatically skipped.

Example YAML (config.example.yaml)

See the config.example.yaml file for all configurable options:

ping:
  interval: 5m
  timeout: 2s
  fail-rate: 0
  targets:
    - 8.8.8.8
    - google.com

http:
  interval: 5m
  timeout: 10s
  targets:
    - https://google.com
    - https://example.com

tcp:
  interval: 5m
  timeout: 5s
  targets:
    - localhost:8080
    - example.com:443
    - 192.168.1.1:22

tls:
  interval: 5m
  timeout: 10s
  targets:
    - google.com:443
    - example.com:443

Usage

The application supports three modes of operation:

1. Configuration File Mode (Recommended)

Run all configured monitoring services in parallel from a YAML configuration file.

Syntax:

izle -config <path/to/config.yaml>

Example:

# Start the service with the example configuration
izle -config config.example.yaml

# Start the service with a custom configuration
izle -config /etc/izle/config.yaml

2. Environment Variables Mode

Run monitoring services using only environment variables. No command or config file needed.

Syntax:

# Just run izle with environment variables set
izle

Supported Environment Variables:

• IZLE_PING_INTERVAL: Ping interval (e.g., 5m, 30s)

• IZLE_PING_TIMEOUT: Ping timeout (default: 2s)

• IZLE_PING_FAIL_RATE: Percentage of fake failures (0-100)

• IZLE_PING_TARGETS: Comma-separated ping targets

• IZLE_PING_ATTEMPTS: Maximum attempts per check

• IZLE_PING_THRESHOLD: Successful attempts required to pass

• IZLE_HTTP_INTERVAL: HTTP interval (e.g., 5m, 30s)

• IZLE_HTTP_TIMEOUT: HTTP timeout (default: 10s)

• IZLE_HTTP_TARGETS: Comma-separated HTTP targets

• IZLE_HTTP_ATTEMPTS: Maximum attempts per check

• IZLE_HTTP_THRESHOLD: Successful attempts required to pass

• IZLE_TCP_INTERVAL: TCP interval (e.g., 5m, 30s)

• IZLE_TCP_TIMEOUT: TCP timeout (default: 5s)

• IZLE_TCP_TARGETS: Comma-separated TCP targets (format: host:port)

• IZLE_TCP_ATTEMPTS: Maximum attempts per check

• IZLE_TCP_THRESHOLD: Successful attempts required to pass

• IZLE_TLS_INTERVAL: TLS interval (e.g., 5m, 30s)

• IZLE_TLS_TIMEOUT: TLS timeout (default: 10s)

• IZLE_TLS_TARGETS: Comma-separated TLS targets (format: host:port)

• IZLE_TLS_ATTEMPTS: Maximum attempts per check

• IZLE_TLS_THRESHOLD: Successful attempts required to pass

• IZLE_TLS_WARN_DAYS: Warn when a certificate expires within this many days (default: 21)

Example:

export IZLE_PING_INTERVAL=30s
export IZLE_PING_TARGETS="8.8.8.8,1.1.1.1,google.com"
export IZLE_HTTP_INTERVAL=1m
export IZLE_HTTP_TARGETS="https://google.com,https://example.com"
izle

3. Command-Based Mode

Run a specific monitoring service with command-line arguments. When using command mode, the -config flag is ignored.

Syntax:

izle <command> [options] [targets]

Available Commands:

Ping Command

izle ping [options] [target1] [target2] ...

Options:

• -config: Path to YAML config file (used for defaults)
• -interval: Interval between checks (e.g., 5m, 30s)
• -timeout: Timeout for each attempt (default: 2s)
• -fail-rate: Percentage of fake failures for testing (0-100)
• -targets: Comma-separated list of targets (IP addresses or domain names)
• -attempts: Maximum attempts per check (default: 3)
• -threshold: Successful attempts required to pass (default: 1)

Environment Variables:

• IZLE_PING_INTERVAL: Interval between checks (e.g., 5m, 30s)
• IZLE_PING_TIMEOUT: Timeout for each attempt
• IZLE_PING_FAIL_RATE: Percentage of fake failures (0-100)
• IZLE_PING_TARGETS: Comma-separated list of targets

Examples:

# Ping a single host
izle ping 8.8.8.8

# Ping multiple hosts (IP and domain names)
izle ping 8.8.8.8 1.1.1.1 google.com

# Ping with custom interval and timeout
izle ping -interval 30s -timeout 3s 8.8.8.8

# Ping with comma-separated targets
izle ping -targets 8.8.8.8,1.1.1.1,google.com

HTTP Command

izle http [options] [target1] [target2] ...

Options:

• -config: Path to YAML config file (used for defaults)
• -interval: Interval between checks (e.g., 5m, 30s)
• -timeout: Timeout for each request (default: 10s)
• -targets: Comma-separated list of targets
• -attempts: Maximum attempts per check (default: 3)
• -threshold: Successful attempts required to pass (default: 1)

Environment Variables:

• IZLE_HTTP_INTERVAL: Interval between checks (e.g., 5m, 30s)
• IZLE_HTTP_TIMEOUT: Timeout for each request
• IZLE_HTTP_TARGETS: Comma-separated list of targets

Examples:

# Check a single HTTP endpoint
izle http https://google.com

# Check multiple endpoints
izle http https://google.com https://example.com https://github.com

# Check with custom timeout
izle http -timeout 15s https://example.com

TCP Command

izle tcp [options] [target1] [target2] ...

Options:

• -config: Path to YAML config file (used for defaults)
• -interval: Interval between checks (e.g., 5m, 30s)
• -timeout: Timeout for each connection attempt (default: 5s)
• -targets: Comma-separated list of targets (format: host:port)
• -attempts: Maximum attempts per check (default: 3)
• -threshold: Successful attempts required to pass (default: 1)

Environment Variables:

• IZLE_TCP_INTERVAL: Interval between checks (e.g., 5m, 30s)
• IZLE_TCP_TIMEOUT: Timeout for each connection attempt
• IZLE_TCP_TARGETS: Comma-separated list of targets (format: host:port)

Examples:

# Check a single TCP port
izle tcp localhost:8080

# Check multiple ports
izle tcp localhost:8080 example.com:443 192.168.1.1:22

# Check with custom timeout
izle tcp -timeout 3s example.com:443

TLS Command

izle tls [options] [target1] [target2] ...

Options:

• -config: Path to YAML config file (used for defaults)
• -interval: Interval between checks (e.g., 5m, 30s)
• -timeout: Timeout for each probe (default: 10s)
• -targets: Comma-separated list of targets (format: domain:port or ip:port)
• -attempts: Maximum attempts per check (default: 3)
• -threshold: Successful attempts required to pass (default: 1)
• -warn-days: Warn when a certificate expires within this many days (default: 21)

Environment Variables:

• IZLE_TLS_INTERVAL: Interval between checks (e.g., 5m, 30s)
• IZLE_TLS_TIMEOUT: Timeout for each probe
• IZLE_TLS_TARGETS: Comma-separated list of targets (format: domain:port or ip:port)

Examples:

# Check a single TLS certificate
izle tls google.com:443

# Check multiple certificates
izle tls google.com:443 example.com:443 github.com:443

# Check with custom timeout
izle tls -timeout 15s example.com:443

Note on mTLS Support: The TLS probe uses certificate-only mode (RunCertOnly), which means it can successfully retrieve certificate information even from endpoints that require mutual TLS (mTLS) authentication. In such cases, the certificate expiry and issuer information will still be logged successfully. If the TLS handshake fails after certificate retrieval (due to missing client certificates), a handshake_error field is included in the log, but the check still reports status: OK, because the certificate was retrieved and is valid.

Note on certificate validity: An incomplete handshake is tolerated; an invalid certificate is not. A certificate that has expired, that is not valid yet, or whose presented chain contains an expired certificate is reported as status: FAIL — answering OK about an expired certificate would defeat the point of monitoring it. The certificate fields are still logged on failure, together with expired and not_yet_valid, since that is exactly when they are needed.

When the leaf certificate is healthy but an intermediate in the presented chain expires earlier, a separate warning carries chain_expires_at, chain_days_remaining and chain_length. That case is invisible if only the leaf is watched: the certificate looks fine right up to the day clients start failing.

Debug logging: -debug, or the IZLE_DEBUG environment variable, raises the log level to debug. On top of izle's own output this turns on the probe library's per-attempt detail in the same JSON stream: every attempt with its duration or error, every ICMP reply skipped as stale or unrelated, and the point at which a check gives up because the remaining attempts can no longer succeed. At the default level the probe library stays silent, so this costs nothing until it is switched on.

izle -debug tcp example.com:443
IZLE_DEBUG=1 izle -config config.yaml

Output: All checks produce JSON logs to stdout, which can be redirected to a file or piped to a log aggregation system.

{"timestamp":"2025-02-28T10:30:45Z","level":"info","message":"Ping success","method":"ping","target":"8.8.8.8","status":"OK","duration_ms":25.5,"attempts":1}
{"timestamp":"2025-02-28T10:30:46Z","level":"info","message":"HTTP check success","method":"http","target":"https://google.com","status_code":200,"status":"OK","duration_ms":156.2,"attempts":1}
{"timestamp":"2025-02-28T10:30:47Z","level":"info","message":"TCP connection success","method":"tcp","target":"localhost:8080","host":"localhost","port":8080,"status":"OK","duration_ms":12.3,"attempts":1}
{"timestamp":"2025-02-28T10:30:48Z","level":"info","message":"TLS check success","method":"tls","target":"google.com:443","host":"google.com","status":"OK","duration_ms":145.8,"attempts":1,"subject":"*.google.com","issuer":"Google Internet Authority G3","expires_at":"2025-12-31T23:59:59Z","days_remaining":308,"protocol":"TLSv1.3","cipher_suite":"TLS_AES_256_GCM_SHA384"}
{"timestamp":"2025-02-28T10:30:49Z","level":"error","message":"TLS check failed","method":"tls","target":"old.example.com:443","host":"old.example.com","status":"FAIL","attempts":1,"subject":"CN=old.example.com","issuer":"CN=Example Issuing CA","expires_at":"2025-02-18T23:59:59Z","days_remaining":-10,"expired":true,"not_yet_valid":false,"error":"certificate expired on 2025-02-18T23:59:59Z (10 days ago)"}
{"timestamp":"2025-02-28T10:30:50Z","level":"warn","message":"TLS chain expires before the certificate itself","method":"tls","target":"api.example.com:443","chain_expires_at":"2025-03-10T12:00:00Z","chain_days_remaining":10,"chain_length":2}

Docker Usage

Build:

docker build -t izle .

The version in the startup banner is stamped at build time; without it the binary reports dev. Docker cannot read the tag it is being built under, so pass the same value to both and the two cannot drift apart:

VERSION=1.2.0
docker build --build-arg VERSION=$VERSION -t netyazilim/izle:$VERSION .

Building outside Docker takes the same flag:

go build -ldflags "-X main.Version=$(git describe --tags --always)" ./cmd/izle

Run with YAML:

# Mount the config.yaml file into the container
docker run --rm -v $(pwd)/config.yaml:/root/config.yaml izle -config /root/config.yaml

Docker Compose:

docker-compose.example.yml is a working deployment to copy and edit. It covers both ways of configuring izle, the resolver options a container wants so a slow DNS server is not reported as a target being down, and what shipping the logs elsewhere looks like.