Qtap Guides

Standalone deployment guides for Qtap with local YAML-based configuration. Maximum control and flexibility for self-managed environments.

What You'll Learn

These guides cover:

  • Local configuration - Writing and managing qtap.yaml files

  • Storage backends - Configuring S3, MinIO, and other object stores

  • Traffic processing - Using plugins, stacks, and rulekit expressions

  • Conditional capture - Smart filtering to reduce noise and costs

  • Production deployment - Best practices for long-term operation

Available Guides

Getting Started

5-Minute Quickstart

The simplest possible Qtap setup - everything outputs to your terminal for immediate visibility.

Perfect for:

  • Quick testing and experimentation

  • Development environments

  • Understanding Qtap basics before adding complexity

What's included:

  • Minimal YAML configuration (15 lines)

  • Stdout-only output (no external services needed)

  • Test commands to verify it works

Time to complete: 5 minutes Skill level: Beginner

Complete Guide - From Hello World to Production

A progressive, hands-on tutorial that takes you from basic setup to production-ready configuration in four levels:

Level 1: Dead Simple - Verify It's Working (5 minutes)

  • Basic qtap configuration

  • Verify HTTPS visibility

  • Understand output format

Level 2: Basic Filtering and Selective Capture (10 minutes)

  • Filter out noisy processes

  • Apply different capture levels by domain

  • Use multiple stacks

Level 3: Conditional Capture with Rulekit (15 minutes)

  • Use rulekit expressions for intelligent capture

  • Create reusable macros

  • Capture only errors and specific request types

Level 4: Production Storage with S3 (20 minutes)

  • Configure S3-compatible object storage

  • Keep sensitive data in your network

  • Implement cost-effective storage strategies

Time to complete: 50 minutes total (or do one level at a time) Skill level: Beginner to Advanced

Ingress Traffic Capture with Python

Learn how to capture incoming HTTP requests to your applications using a Python FastAPI server example.

Perfect for:

  • Monitoring API endpoints you expose

  • Debugging incoming client requests

  • Security auditing of inbound traffic

  • Understanding ingress vs egress capture

What's included:

  • Complete FastAPI server example

  • Ingress-specific Qtap configuration

  • Step-by-step testing instructions

  • Loopback traffic handling

Key concepts:

  • direction: ingress configuration

  • ignore_loopback: false for localhost capture

  • Full request/response visibility for incoming traffic

Time to complete: 15 minutes Skill level: Beginner

Web Server Integration

Capturing NGINX Traffic

Monitor HTTP traffic flowing through NGINX reverse proxy with process-aware visibility.

Time to complete: 30 minutes Skill level: Beginner-Intermediate

Capturing Caddy Traffic

Observe HTTP traffic in Caddy web server environments.

Time to complete: 30 minutes Skill level: Beginner-Intermediate

Capturing Traefik Traffic

Capture cloud-native proxy traffic with Traefik integration.

Time to complete: 30 minutes Skill level: Beginner-Intermediate

Capturing HAProxy Traffic

Load balancer analytics and visibility with HAProxy.

Time to complete: 30 minutes Skill level: Intermediate

Capturing Envoy Traffic

Service mesh visibility with Envoy proxy.

Time to complete: 30 minutes Skill level: Intermediate

Observability & Integration

Monitoring Qtap with Prometheus and Grafana

Complete guide to setting up observability for Qtap using Prometheus metrics and Grafana dashboards.

What you'll learn:

  • Exposing Qtap's Prometheus metrics endpoints

  • Configuring Prometheus to scrape metrics

  • Importing and customizing Grafana dashboards

  • Setting up alerts for error rates and latency

  • Optimizing metrics for production

What's included:

  • Prometheus configuration examples (Docker Compose + Kubernetes)

  • Pre-built Grafana dashboard with RED metrics

  • Alert rules for errors, latency, and traffic spikes

  • PromQL queries for troubleshooting

  • Production optimization tips

Perfect for:

  • Production deployments requiring observability

  • Teams using existing Prometheus/Grafana stacks

  • Performance monitoring and capacity planning

  • SRE teams managing Qtap at scale

Time to complete: 45 minutes Skill level: Intermediate

Sending Qtap Events to OpenTelemetry

Send Qtap network observability data to any OpenTelemetry-compatible backend using the OTLP protocol.

What you'll learn:

  • Exporting Qtap events as OpenTelemetry Logs

  • Configuring OTLP endpoints (gRPC and HTTP)

  • Deploying with OpenTelemetry Collector

  • Backend-specific configurations (Datadog, Honeycomb, New Relic, Grafana Cloud, Elastic)

  • Understanding log event structure and attributes

  • Querying and filtering events

What's included:

  • Docker Compose setup with OTel Collector

  • Kubernetes deployment with OpenTelemetry Operator

  • Configuration examples for major observability platforms

  • Complete log structure documentation

  • Troubleshooting guide

Perfect for:

  • Teams using existing OpenTelemetry infrastructure

  • Organizations standardizing on OTLP

  • Multi-platform observability strategies

  • Sending data to SaaS observability platforms

Key insight: Qtap exports events as OpenTelemetry Logs (not traces), making it compatible with any log aggregation or observability platform that supports OTLP. Events include connection metadata and HTTP transaction summaries (artifact_record events) with rich structured attributes.

Time to complete: 30 minutes Skill level: Intermediate

Capturing All HTTP Traffic with Fluent Bit

High-volume batching and processing with Fluent Bit integration.

Time to complete: Variable Skill level: Intermediate-Advanced

Advanced Use Cases

HTTPS Header Capture Without Proxies

Deep dive into how Qtap uses eBPF to capture HTTPS traffic without proxies, certificates, or decryption.

What you'll learn:

  • How eBPF hooks into TLS libraries (OpenSSL, GoTLS, etc.)

  • Capturing plaintext before encryption happens

  • Using rulekit expressions for conditional capture

  • Storing captured data in S3

  • Analyzing captured traffic with jq

Perfect for:

  • Understanding how eBPF enables TLS visibility

  • Security teams evaluating the technology

  • Advanced users who want granular control

Time to complete: 30 minutes Skill level: Intermediate

CI Security Validation

Build pipeline validation and security checks with Qtap.

Time to complete: Variable Skill level: Advanced

Why Choose Qtap Standalone?

Maximum Control

  • Full control over configuration via YAML

  • Version control your configs with git

  • No dependency on external control plane

Data Sovereignty

  • All data stays in your network

  • Configure your own S3-compatible storage

  • No external API calls (except to your chosen storage)

Flexibility

  • Run in air-gapped environments

  • Customize every aspect of traffic processing

  • Use with your existing tooling and workflows

Next Steps

New to Qtap? Start with the 5-Minute Quickstart or the comprehensive Complete Guide.

Integrating with web servers? Browse our Web Server Integration guides for NGINX, Caddy, Traefik, HAProxy, and Envoy.

Need observability? Check out Prometheus/Grafana, OpenTelemetry, or Fluent Bit integration.

Want centralized management? Check out the Qplane Guides for cloud-connected deployment.

PreviousGuidesNextGetting Started

Last updated