Documentation
  • Introduction
    • How It Works
    • Architecture & Data Flow
    • Why another Agent?
    • eBPF Concepts
    • Use Cases
  • Deployment
  • Qtap
    • Getting Started
    • System Requirements
    • Installation
      • Linux Binary
      • Docker Container
      • Helm Chart
      • Kubernetes Manifest
    • Configuration
      • Storage Configuration
      • Traffic Processing with Plugins
      • Traffic Capture Settings
      • Configuration Examples
  • Qplane
    • Getting Started
      • Create an Account
      • Install Qtap
      • Review your Dashboards
    • Installation
      • Linux Binary
      • Docker Container
      • Helm Chart
    • Configuration
  • Security & Compliance
  • License
  • Appendix
    • Qcontrol (Beta)
    • Java
    • Object Storage
      • Google Cloud Storage
    • S3 Credentials for Qtap using Kubernetes Secrets
  • FAQ
Powered by GitBook
On this page
  • Prerequisites
  • Demo Script
  • Docker Demo
  • Step 1: Create a Simple Qpoint Configuration File
  • Step 2: Run the Qpoint Tap Agent
  • Step 3: Generate Some Test Traffic
  • Step 4: View the Captured Traffic
  • Step 5: Test Specific Use Cases
  1. Qtap

Getting Started

PreviousQtapNextSystem Requirements

Last updated 11 days ago

This guide will help you quickly set up Qpoint locally to start capturing and analyzing your service connections within minutes.

Before getting started, we recommend checking the for details on Qtap compatibility. If you'd like to automatically verify your environment's compatibility, use the following:

curl -sSL https://github.com/qpoint-io/preflight/releases/latest/download/preflight.sh | sudo bash

Prerequisites

  • A Linux host with kernel 5.10+ (check with uname -r)

  • Docker installed

  • root/sudo permissions

Demo Script

# Run Qtap in demo mode
$ curl -s https://get.qpoint.io/demo | sudo sh

Docker Demo

Step 1: Create a Simple Qpoint Configuration File

# Create a directory for your configuration
mkdir -p ~/qpoint-demo/config
# Create the configuration file
cat > ~/qpoint-demo/config/qpoint.yaml << 'EOF'
version: 2

services:
  event_stores:
    - id: console_stdout
      type: stdout
  
  object_stores:
    - id: console_stdout
      type: stdout

stacks:
  default_stack: # Stack Name
    plugins:
      - type: access_logs
        config:
          mode: details # Default action (summary|details|full)
          format: console # (json|console)

tap:
  direction: egress
  ignore_loopback: false
  audit_include_dns: true
  http:
    stack: default_stack
EOF

Step 2: Run the Qpoint Tap Agent

Now, deploy the Qtap agent:

docker run -d \
  --name qtap \
  --user 0:0 \
  --privileged \
  --cap-add CAP_BPF \
  --cap-add CAP_SYS_ADMIN \
  --pid=host \
  --network=host \
  -v /sys:/sys \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/qpoint-demo/config:/app/config \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qpoint:v0 \
  tap \
  --log-level=info \
  --log-encoding=console \
  --config=/app/config/qpoint.yaml

Step 3: Generate Some Test Traffic

Let's create some test traffic to see Qpoint in action:

# Create a test container and send HTTP requests
docker run --rm --name test-client curlimages/curl \
  sh -c "curl -v https://httpbin.org/get && \
         curl -v https://httpbin.org/status/404 && \
         curl -v https://httpbin.org/status/500"

Step 4: View the Captured Traffic

Check the Qtap logs to see the traffic being captured:

docker logs qtap -f

You should see log entries showing:

  • Connection details (source, destination, protocol)

  • HTTP request and response metadata

  • Full request and response payloads in the console

  • Error information for the 404 and 500 responses

Example output snippet:

===================================================================
curl → GET https://httpbin.org/status/500 503 Service Unavailable
===================================================================

------------------ META ------------------
PID: 194603
Exe: /usr/bin/curl
Container ID: 6f4fccfae3f7
Direction: egress-external
Bytes Sent: 46
Bytes Received: 232

------------------ REQUEST ------------------
GET httpbin.org http2
Accept: */*
Qpoint-Request-Id: cvct1q87p3qj89ieqtlg
:authority: httpbin.org
:method: GET
:path: /status/500
:scheme: https
User-Agent: curl/8.12.1

------------------ RESPONSE ------------------
503 Service Unavailable
:status: 503
Server: awselb/2.0
Date: Tue, 18 Mar 2025 20:00:41 GMT
Content-Type: text/html
Content-Length: 162

Step 5: Test Specific Use Cases

Now that Qpoint is running, you can try various use cases to see more capabilities:

Capture API Authentication Issues

# Test missing or invalid API key
docker run --rm --name test-auth curlimages/curl \
  -v https://httpbin.org/bearer -H "Authorization: Bearer invalid-token"

Monitor Third-Party API Health

# Create a loop to periodically check an API
docker run --rm --name test-health curlimages/curl \
  sh -c "for i in {1..5}; do curl -s https://httpbin.org/status/200,200,200,500 > /dev/null; sleep 2; done"

Track Slow Responses

# Test a delayed response
docker run --rm --name test-delay curlimages/curl \
  https://httpbin.org/delay/2

system requirements