# 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](https://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

{% hint style="info" %}
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.
{% endhint %}

***

## 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

{% hint style="info" %}
**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.
{% endhint %}

**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.

{% hint style="info" %}
**Skip this step** if you only want to explore Qplane with your existing agent. You can always add more agents later.
{% endhint %}

### Create a Registration Token

1. In Qplane, navigate to **Settings → Environments**
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

{% hint style="warning" %}
Treat this token as a secret! It provides access to your organization. Store it securely.
{% endhint %}

### Choose Your Installation Method

{% tabs %}
{% tab title="Docker" %}
**Run the preflight check** (optional but recommended):

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

**Install Qtap:**

```bash
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:**

```bash
docker logs qtap 2>&1 | head -20
```

You should see initialization logs showing the agent connecting to Qplane.
{% endtab %}

{% tab title="Kubernetes (Helm)" %}
**Add the Qpoint Helm repository:**

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

**Install Qtap:**

```bash
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:**

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

{% endtab %}

{% tab title="Linux Binary" %}
**Download and install:**

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

**Configure with your token:**

```bash
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):

```bash
sudo systemctl enable qtap
sudo systemctl start qtap
sudo systemctl status qtap
```

{% endtab %}
{% endtabs %}

### Verify Agent Connection

1. In Qplane, navigate to **Settings → Environments**
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:

```bash
# 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:

```bash
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

{% hint style="info" %}
**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.
{% endhint %}

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**

{% hint style="info" %}
**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.
{% endhint %}

### Test the Routing

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

**Generate test traffic again:**

```bash
curl https://httpbin.org/get
```

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

{% tabs %}
{% tab title="Docker" %}

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

{% endtab %}

{% tab title="Kubernetes" %}

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

{% endtab %}

{% tab title="Linux Binary" %}

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

{% endtab %}
{% endtabs %}

**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](https://docs.qpoint.io/getting-started/qplane/configuration/stacks-and-plugins) - Deep dive into all available plugins
* [Alerting](https://docs.qpoint.io/getting-started/qplane/configuration/alerting) - Set up alerts for errors and latency
* [Settings](https://docs.qpoint.io/getting-started/qplane/configuration/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

### Need Help?

* Report issues: [GitHub Issues](https://github.com/qpoint-io/qtap/issues)
* Check compatibility: Run the [preflight script](https://github.com/qpoint-io/preflight)

***

*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.*