Hello World - Your First 30 Minutes

This guide walks you through your first steps with Qplane after deploying your initial agent. You've completed the installation wizard, you see the default setup—now what? Follow this guide to understand what you're seeing, generate test traffic, and start customizing your configuration.

What you'll accomplish:

• Understand the default Qplane setup

• Add additional Qtap agents to your environment

• Generate test traffic and see it in your dashboards

• Customize your first stack and routing rule

Time to complete: 30 minutes

Prerequisites:

• A Qplane account at app.qpoint.io with your first agent deployed

• A Linux server or Kubernetes cluster to install additional Qtap agents (optional)

• Docker, Kubernetes, or Linux with systemd

When you create a Qplane account, the installation wizard guides you through deploying your first Qtap agent. You must complete this initial deployment before you can access the Qplane interface. This guide picks up after that first agent is running.

---

Step 1: Understanding Your Default Setup

Now that you've deployed your first agent via the installation wizard, let's explore the pre-configured environment that Qplane has set up for you.

What's Already Configured

Default Stack: "Basic - Reporting and Error Detection"

Navigate to Plugins → Stacks to see your default stack. It includes:

1. Report Usage Plugin

   • Sends anonymized metrics to Qplane

   • Powers your Traffic, Inventory, and Dashboard pages

   • Required for alerting to work

2. Detect Errors Plugin (with 7 pre-configured rules)

   • App Error (500)

   • Infrastructure Outage (502, 503, 520-523, 525-526, 530)

   • Client Error (400)

   • Authentication Error (401, 403, 407)

   • Rate Limited (429)

   • Not Found (404)

   • Slow Response (configurable threshold)

Default Services

Navigate to Settings → Deploy → Services to see where your data goes:

• Event Store: Qpoint Cloud (Pulse) - anonymized metadata for dashboards

• Object Store: Qpoint Cloud - captured HTTP request/response details

For production use, you should configure your own S3-compatible object store to keep sensitive data within your network. The Qpoint Cloud object store is for preview and testing only.

Default Routing

Navigate to Plugins → Routing to see traffic routing:

• Default Stack: All traffic uses "Basic - Reporting and Error Detection"

• Endpoints: None configured yet (we'll add one later)

What This Setup Does

With the default configuration, Qtap will:

• ✅ Capture all outbound (egress) HTTP/HTTPS traffic

• ✅ Send anonymized connection metadata to Qplane dashboards

• ✅ Capture full request/response details when errors occur (4xx, 5xx status codes)

• ✅ Upload error details to Qpoint Cloud object store

• ✅ Show traffic in real-time on your dashboards

---

Step 2: Add Additional Qtap Agents (Optional)

You already deployed your first agent during account creation. If you want to add more agents to monitor additional servers or clusters, follow these steps.

Skip this step if you only want to explore Qplane with your existing agent. You can always add more agents later.

Create a Registration Token

1. In Qplane, navigate to Settings → Installations

2. Click + Installation

3. Enter a name (e.g., "Production Cluster" or "Staging Environment")

4. Copy the generated token—you'll need it for installation

Treat this token as a secret! It provides access to your organization. Store it securely.

Choose Your Installation Method

Docker

Run the preflight check (optional but recommended):

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

Install Qtap:

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 \
  -e TINI_SUBREAPER=1 \
  --ulimit=memlock=-1 \
  us-docker.pkg.dev/qpoint-edge/public/qtap:v0 \
  --registration-token=YOUR_TOKEN_HERE \
  --log-level=info \
  --log-encoding=console

Replace YOUR_TOKEN_HERE with your registration token.

Verify it's running:

docker logs qtap 2>&1 | head -20

You should see initialization logs showing the agent connecting to Qplane.

Kubernetes (Helm)

Add the Qpoint Helm repository:

helm repo add qpoint https://qpoint-io.github.io/charts
helm repo update

Install Qtap:

helm install qtap qpoint/qtap \
  --set config.registrationToken=YOUR_TOKEN_HERE \
  --set config.logLevel=info

Replace YOUR_TOKEN_HERE with your registration token.

Verify it's running:

kubectl get pods -l app.kubernetes.io/name=qtap
kubectl logs -l app.kubernetes.io/name=qtap --tail=20

Linux Binary

Download and install:

curl -sSL https://get.qpoint.io/install | sudo bash

Configure with your token:

sudo qtap \
  --registration-token=YOUR_TOKEN_HERE \
  --log-level=info \
  --log-encoding=console

Replace YOUR_TOKEN_HERE with your registration token.

Run as a service (optional):

sudo systemctl enable qtap
sudo systemctl start qtap
sudo systemctl status qtap

Verify Agent Connection

1. In Qplane, navigate to Settings → Installations

2. You should see your installation listed

---

Step 3: Generate Test Traffic

Now that Qtap is running, let's generate some test traffic to see it appear in Qplane.

Generate HTTP Requests

From the same machine where Qtap is running, generate some test traffic:

# Success request (should appear in dashboards)
curl https://httpbin.org/get

# Error request (should trigger error detection)
curl https://httpbin.org/status/500

# Another error
curl https://httpbin.org/status/404

If using Kubernetes, exec into any pod:

kubectl run test-curl --rm -it --image=curlimages/curl --restart=Never -- sh
# Inside the pod:
curl https://httpbin.org/get
curl https://httpbin.org/status/500
curl https://httpbin.org/status/404
exit

Wait for Data to Appear

Give it 30-60 seconds for data to flow through the system.

---

Step 4: Explore Your Dashboards

Let's see the traffic you just generated in Qplane's dashboards.

View Traffic

1. Navigate to Traffic (main navigation)

2. You should see entries for httpbin.org

3. Click on an entry to see details:

   • Request method, path, status code

   • Response time

   • Source process (curl)

   • Timestamp

View Inventory

1. Navigate to Inventory

2. You'll see httpbin.org listed as a vendor

3. Click on it to see:

   • Total requests

   • Error rate

   • Endpoints called

   • Clients making requests

View Error Details

1. Navigate to Traffic → HTTP Requests

2. Look for the 500 and 404 status codes you generated

3. Click on an error entry to see:

   • Full request headers

   • Full response headers and body

   • Which process made the request

   • Timestamp and duration

This is the power of Qplane: You can see inside HTTPS traffic without proxies or certificate management, and errors are automatically captured with full details.

---

Step 5: Customize Your First Stack

Now let's create a custom stack for a specific use case. We'll create a "Debug Stack" for troubleshooting.

Create a Debug Stack

1. Navigate to Plugins → Stacks

2. Click + New Stack

3. Configure the stack:

   • Name: Debug Stack

   • Description: Full logging and capture for troubleshooting specific integrations

4. Click into the new stack to add plugins

5. Click + Add Plugin and add:

   • Report Usage (no configuration needed)

   • Access Logs:

     • Mode: full

   • Detect Errors:

     • Keep default rules enabled

6. Enable Auto generate release on every change

7. Click Save

Enable Debug Rule for Full Capture

To capture all traffic (not just errors) to your object store:

1. In your Debug Stack, click the Reliability tab

2. Find the Debug rule

3. Enable it by toggling it on

4. Click Save

This rule captures all HTTP transactions with full details and uploads them to your object store.

What This Stack Does

The Debug Stack provides maximum visibility:

• Report Usage: Metrics still flow to dashboards

• Access Logs: Prints all HTTP transactions to the agent's stdout (visible in logs)

• Detect Errors: Default rules capture errors and upload to object store

• Debug Rule (when enabled): Captures ALL traffic (including successes) and uploads to object store

Access Logs vs. Detect Errors/Debug: Access Logs only prints to stdout for viewing in agent logs. To capture and upload traffic to your object store, use the Debug rule under Reliability → Rules.

This is useful when troubleshooting a specific integration—you get complete request/response details both in agent logs (Access Logs) and in your object store (Debug rule).

---

Step 6: Create Your First Routing Rule

Let's assign a specific domain to use your new Debug Stack. Routing in Qplane determines which stack processes traffic from each domain—it's not about proxying or redirecting traffic, but rather which processing pipeline (stack) handles it.

Add a Routing Rule

1. Navigate to Plugins → Routing

2. Scroll to the Endpoints section

3. Click + Add Endpoint

4. Configure the endpoint:

   • Domain: httpbin.org

   • Stack: Debug Stack

5. Click Save

What is Routing? Routing assigns domains to stacks. When Qtap captures traffic to httpbin.org, it will process that traffic using your Debug Stack (with Access Logs and Debug rule enabled) instead of the default stack. All other traffic continues using the default "Basic - Reporting and Error Detection" stack.

Test the Routing

Now traffic to httpbin.org will be processed by your Debug Stack instead of the default stack.

Generate test traffic again:

curl https://httpbin.org/get

Check the agent logs to see full request/response details:

Docker

docker logs qtap 2>&1 | grep -A 30 "httpbin.org"

Kubernetes

kubectl logs -l app.kubernetes.io/name=qtap --tail=50 | grep -A 30 "httpbin.org"

Linux Binary

sudo journalctl -u qtap -n 50 | grep -A 30 "httpbin.org"

What you should see in agent logs (from Access Logs plugin):

• Full URL: https://httpbin.org/get

• Request headers (Host, User-Agent, etc.)

• Response headers (Content-Type, etc.)

• Response body (the JSON response from httpbin)

This is the Access Logs plugin printing to stdout because you routed httpbin.org to your Debug Stack.

Additionally (from Debug rule): The full transaction is also captured and uploaded to your object store, where you can view it later in Qplane under Traffic → HTTP Requests.

---

Step 7: Understanding the Data Flow

Now that you've seen it in action, let's understand what's happening:

When Traffic Occurs

1. Qtap captures traffic at the kernel level using eBPF

2. Traffic flows through the assigned stack:

   • For httpbin.org: Uses your Debug Stack

   • For everything else: Uses the default "Basic - Reporting and Error Detection" stack

3. Plugins process the traffic:

   • Report Usage: Sends anonymized metadata to Qplane (Pulse)

   • Access Logs (Debug Stack only): Writes full details to stdout

   • Detect Errors: Checks status codes, captures errors

4. Data reaches destinations:

   • Events (anonymized metadata): → Qplane dashboards (Traffic, Inventory)

   • Objects (full HTTP details): → Qpoint Cloud object store (for errors)

   • Logs (Access Logs output): → Agent stdout/logs

What's Anonymized vs. Sensitive

Anonymized event metadata (goes to Qplane dashboards):

• Connection counts

• HTTP method, status code

• Domain, path (URL structure)

• Response time, bytes transferred

• Source container/process name

• No headers, no bodies

Sensitive object data (goes to object store):

• Full request headers

• Full request body

• Full response headers

• Full response body

• Only captured for errors (with default stack)

---

What's Next?

🎉 Congratulations! You've completed the Qplane Hello World. You now know how to:

• ✅ Understand the default Qplane setup

• ✅ Install and connect a Qtap agent

• ✅ Generate traffic and see it in dashboards

• ✅ Create custom stacks for different traffic types

• ✅ Route specific domains to specific stacks

• ✅ Understand the data flow and what's captured

Next Steps

Level Up Your Configuration:

• Stacks & Plugins - Deep dive into all available plugins

• Alerting - Set up alerts for errors and latency

• Settings - Configure filters, services, and advanced options

Production Readiness:

• Configure S3 storage: Keep sensitive data in your network

  • Navigate to Settings → Deploy → Services → Object Stores

  • Click + Add Object Store and select S3 Endpoint

  • Configure your MinIO, AWS S3, or GCS bucket

• Filter noisy processes: Reduce noise from health checks

  • Navigate to Settings → Qtap → Filters

  • Enable filters for Kubernetes, Container Runtimes, etc.

• Refine error detection: Customize which errors to capture

  • Navigate to Plugins → Stacks → Basic - Reporting and Error Detection

  • Click Reliability tab to adjust error rules

Advanced Use Cases:

• Getting Started - Complete Guide - Progressive Qtap configuration levels

• Transparent HTTPS Header Capture Without Proxies - How eBPF enables TLS visibility

Need Help?

• Report issues: GitHub Issues

• Check compatibility: Run the preflight script

---

This guide uses the default Qplane cloud services for simplicity. For production deployments with sensitive data, configure your own S3-compatible object storage to ensure data sovereignty.