Getting Started
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 system requirements 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
installedroot/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
Last updated