How It Fits Together

This guide ties together the Qpoint platform’s architecture, the Qplane (web console) control plane and the Qtap agent/YAML configuration. It explains what each component does, how they interact, and where specific functionality lives—whether in YAML, in Qplane UI or both.

1. Qpoint Architecture and Data Flow

Qpoint is built on a multi-layer architecture designed for deep visibility while preserving data sovereignty:

Qtap (Data Plane) – A lightweight eBPF agent you run on your servers. It attaches to kernel socket functions and TLS/SSL library calls to capture connection metadata and payloads with minimal overhead. Qtap supports native TLS integration for common libraries (OpenSSL, GoTLS, NodeTLS, Java) or an egress-controller mode for custom TLS implementations.

Qplane (Control Plane) – Hosted at app.qpoint.io, Qplane is the centralized management and visualization interface. You use it to configure Qtap agents, manage plugins and stacks, define filters and routing rules, create alerting rules and view dashboards. Qplane only processes anonymized event metadata (connection attributes, status codes, etc.) and never accesses sensitive payloads. Payloads remain in your environment.

Qscan (Data Classification) – An optional service you run to perform deep inspection and classification of payloads (PII, credentials, secrets). Qtap sends payloads to Qscan for analysis, and Qscan runs entirely within your environment.

Object Storage – Your S3-compatible bucket (AWS S3, MinIO, GCS) stores captured payload data. Qtap uploads request/response headers and bodies directly to this bucket. Qplane never sees this data; instead, it provides signed URLs so your browser can fetch the payloads directly.

The data flow distinguishes between events (non-sensitive metadata) and objects (sensitive payloads). Events go to Qplane/Pulse (ClickHouse) for dashboards and alerting, while objects go to your object store or Qscan. A typical qtap.yaml shows this separation: event stores of type pulse send anonymized metadata to the Qpoint cloud, while object stores of type s3 send payloads to your bucket; a qscan entry sends payloads to your Qscan instance.

2. Qtap Configuration via YAML

Qtap’s behavior is controlled by a YAML file (qpoint.yaml/qtap.yaml). Key sections include:

services – Defines where events, objects and Qscan payloads are sent. Examples:

services:
  event_stores:
    - id: qpoint_cloud
      type: pulse
      url: https://api-pulse.qpoint.io
  object_stores:
    - id: aws_s3
      type: s3
      endpoint: s3.amazonaws.com
      bucket: my-company-qpoint-data
      region: us-west-2
      access_key:
        type: env
        value: AWS_ACCESS_KEY_ID
      secret_key:
        type: env
        value: AWS_SECRET_ACCESS_KEY
  qscan:
    type: client
    url: https://qscan.internal.example.com
    token:
      type: env
      value: QSCAN_TOKEN

stacks – Named collections of plugins that define how to process traffic. Each stack contains one or more plugins (e.g., http_capture, access_logs, report_usage, detect_errors). You can create multiple stacks for different traffic types.

tap – Defines what traffic to capture and how to apply stacks. Parameters include:

  • direction – e.g., egress, egress-external, egress-internal, ingress, all.

  • ignore_loopback and audit_include_dns – control loopback and DNS capture.

  • filters – ignore processes by group (kubernetes, container, qpoint, gke, eks) or custom executables.

  • http.stack – default stack for HTTP traffic.

  • endpoints – assign specific domains to specific stacks for fine-grained control.

rulekit – Optional; defines macros and expressions used in plugin rules (e.g., capture POST requests or errors). These rules are used by plugins like http_capture for conditional capture.

Qtap can be deployed using Docker, Kubernetes or directly on Linux. You can either create the YAML manually or configure it through Qplane and download the snapshot YAML.

2.1 Config File vs. Cloud-Connected Registration Tokens

Qpoint offers two deployment models for Qtap, each suited to different scenarios:

  • Local deployment with a self-managed configuration file. You supply a complete qtap.yaml to the agent at startup (via a volume mount or environment variable). This file defines all services, stacks, tap settings and rulekit rules. Benefits: no Qpoint account is required, immediate visibility, self-contained operation and minimal setup—perfect for testing or air-gapped environments. Drawback: any configuration changes require editing the file and redeploying the agent.

  • Cloud-connected mode using a registration token. Instead of providing a config file, you register each Qtap agent with Qplane by supplying a registration token. Generate the token in the Qplane dashboard under Settings → Installations. Start Qtap with this token by passing the --registration-token flag to the agent (for example, sudo qtap --registration-token=$TOKEN or docker run … tap --registration-token=YOUR_TOKEN). The agent then fetches the organization-wide configuration from the control plane and remains synchronized. This model provides centralized management, advanced analytics and multi-environment visibility. Configuration changes in Qplane automatically propagate to all connected agents within minutes, and you can issue separate tokens per environment (dev, staging, prod) to track installations.

Because registration tokens grant access to your organization, treat them as sensitive: store them securely, restrict access, rotate them periodically and revoke them immediately if compromised.

3. Qplane: Control Plane and UI

Qplane extends beyond simple visualization—it's where you centrally manage Qtap agents and configuration without editing YAML directly. Key control features include:

3.1 Stacks & Plugins

Under Plugins → Stacks, you see all defined stacks (Default, Sensitive Data, Debug, Ignore) and can create new ones. Each stack corresponds to a YAML entry under stacks. When you edit a stack in Qplane, you choose plugins and set their parameters; for example, the http_capture plugin supports capture levels (none, summary, details, full) and can include rulekit rules. Changes made here are reflected in the snapshot YAML.

Routing (under Plugins) lets you map domains to stacks visually. This UI maps directly to the endpoints section of the YAML.

3.2 Qtap Settings

In Settings, you control organization-wide and agent-specific settings:

  • Qtap → Config – Choose the audit log destination (event store), traffic direction and advanced capture options (loopback, DNS). These map to services.event_stores and tap settings.

  • Qtap → Filters – Toggle ignoring Kubernetes, container runtimes, GKE/EKS or Qpoint processes, and define custom filters. Maps to tap.filters settings.

  • Deploy → Services – Configure Object Stores, Event Stores and Qscans. This corresponds to services.object_stores, services.event_stores and services.qscan.

  • Deploy → Snapshot – Displays the auto-generated qpoint.yaml reflecting all current settings. You can copy or download this YAML to use in code-based deployments.

3.3 Alerting (Exclusive to Qplane)

Alerting is not configured via YAML; it is managed entirely within Qplane. The Alerting module provides real-time monitoring and notification capabilities for API performance, reliability and infrastructure metrics. It consists of four parts:

  • Rules – Define when an alert should trigger. Pre-built templates (Critical Latency, High Error Rate, Vendor Availability Drop) or custom rules.

  • Filters – Narrow a rule’s scope to vendors, endpoints, clients or environments.

  • Integrations – Define where alerts are delivered (webhooks, Slack, PagerDuty).

  • Events Dashboard – View alert history and timelines. Built on anonymized event data.

Because alerting is exclusive to Qplane, these rules do not appear in the snapshot YAML.

3.4 Filtering & Views

Qplane provides two mechanisms for slicing anonymized event data:

Ad-hoc filters – Available on Inventory and Traffic pages. Click the purple “+” button near the date range to open filtering options by metadata such as Agent, Container, Vendor or HTTP Method. Filters are temporary, resetting when the page reloads.

Views (preconfigured filters & RBAC) – If you routinely need the same filter combination, Qplane lets you save it as a View and optionally restrict access to specific users. A View is essentially a saved query: it stores one or more filter criteria and can be assigned to team members. You manage Views under Settings → Views, where you’ll see a list of existing views and a New View button. Each view has a name, description, a Filters section and a Team section. The Filters section lists the criteria (e.g., Container Image: ...or-go:1.17), and the Team section lists users allowed to use that view. Only users added here will see the view in their View drop-down; removing a user revokes access.

Switching views is done via the View drop-down in the top-left of the dashboard (beside the organization selector). By default, All is selected, showing unfiltered data. Choosing a custom view applies its filters across applicable pages. For example, selecting Hood’s View (a view filtered to a specific container image) causes the Inventory and Traffic tables to display No Records for entities outside that container, effectively sandboxing the user’s visibility. This mechanism supports role-based access control (RBAC): you can create views that limit certain users to a subset of the data without granting them global access. Views live entirely in Qplane; there is no YAML representation for them.

Persistent views are particularly useful when different teams need different perspectives—APM teams might have a view filtered to application domains, security teams might view only high-severity issues, and SRE teams might focus on a particular environment. Because views are UI-only constructs, you can adjust filters or reassign users without redeploying agents or modifying the YAML.

4. Putting It All Together

Here’s how you might deploy and manage Qpoint end-to-end:

  1. Plan your data flow. Decide where anonymized events should go (Pulse/Qplane) and where payloads should be stored (S3/GCS/MinIO) and classified (Qscan). Define these in the services section of your YAML or through Qplane’s Services UI.

  2. Define stacks and plugins. For basic setups, create a default_stack with the http_capture plugin at summary or full level. For more advanced use cases, define additional stacks (Debug, Sensitive Data) and configure plugins like report_usage, detect_errors, access_logs or qscan. Use Qplane’s Stacks UI to create and manage these stacks.

  3. Configure capture settings. Use the tap section (or Qplane’s Config/Filters pages) to choose traffic direction, ignore loopback or DNS, filter out noisy processes and map specific domains to specific stacks. These settings ensure you capture only what matters.

  4. Deploy the agent. Install the Qtap agent on your servers or Kubernetes nodes. Provide the generated YAML via volume mount or environment variable.

  5. Use Qplane for control and visibility. Once agents are running, log into Qplane to:

    • Monitor live metrics and dashboards.

    • Adjust stacks, plugins and filters; watch the snapshot YAML update accordingly.

    • Configure alerting rules, integrations and events dashboards. Remember: alerting lives exclusively in Qplane and is not part of YAML.

    • Invite team members and set roles; configure SSO.

    • Download the Snapshot YAML at any time to reconcile UI settings with code-based deployments or version control your configuration.

  6. Iterate and optimize. Use historical events and alert patterns to refine your rules and thresholds. Tune capture levels and filters to balance visibility with cost and performance.

5. Key Takeaways

  • Separation of Control and Data: Qplane handles management and visualization; Qtap handles data capture. Events (metadata) go to Qplane/Pulse; objects (payloads) go to your object store and optional Qscan.

  • YAML vs UI: The YAML file controls agent behavior (services, stacks, tap settings and rulekit rules). Qplane can generate and update this YAML through the snapshot, but some features—particularly alerting, dashboards, team management and SSO—exist only in the UI and are not present in the YAML.

  • Plugin & Stack Management: Stacks group plugins to process traffic. Use http_capture for capturing HTTP transactions with flexible levels; report_usage and detect_errors generate events; access_logs provides aggregated logs; qscan sends payloads to Qscan for classification.

  • Alerting: Qplane provides a rich alerting system with templates and custom rules, filters to reduce noise, webhook integrations for notifications and a comprehensive events dashboard. This system operates on aggregated event data and does not require YAML configuration.

  • Centralized Management: With Qplane you can manage hundreds of agents, share dashboards, collaborate with your team and integrate notifications—all from a single portal.

By understanding where each capability resides, you can confidently design your Qpoint deployment—using YAML for repeatable agent configuration and Qplane for centralized control, alerting and visualization.

PreviousAlertingNextStacks & Plugins

Last updated