Agentsview Telemetry Reporting Mechanism Using PostHog: Complete Implementation Guide

Agentsview streams anonymized usage data to PostHog through a structured reporter that manages persistent install IDs, whitelists specific events, and transmits periodic heartbeat pings every 24 hours when telemetry is enabled via environment variables.

Agentsview, an open-source agent orchestration platform written in Go, implements a privacy-conscious telemetry system to monitor daemon health and adoption. The telemetry reporting mechanism using PostHog in agentsview relies on the external go.kenn.io/kit/telemetry library, wrapped in a custom abstraction layer that handles configuration, event filtering, and graceful shutdown.

Configuration and Environment Detection

The reporter initializes only when telemetry is explicitly enabled and the binary is not running under test conditions. Agentsview checks the AGENTSVIEW_TELEMETRY_ENABLED environment variable (falling back to the generic GENERIC_TELEMETRY_ENABLED from the Kenn kit) to determine activation state.

The initialization logic in cmd/agentsview/main.go ensures that go test executions automatically disable telemetry to prevent polluting production datasets. When disabled, the system returns a no-op reporter that silently discards events without network overhead.

Reporter Construction and Install ID Management

The telemetry.NewReporterOrDisabled function in internal/telemetry/telemetry.go constructs the reporting pipeline. This process involves three critical steps:

1. Install ID Persistence – The system generates or retrieves a unique telemetry-install-id stored in the configured data directory (opts.DataDir). This identifier persists across restarts to track unique installations without collecting personally identifiable information.

2. Client Initialization – The function invokes kittelemetry.NewPostHogReporter from the Kenn kit, passing the install ID, application name (agentsview), version string, git commit hash, and source label (daemon).

3. Wrapper Creation – The returned *telemetry.Reporter wraps the underlying kittelemetry.PostHogReporter, which manages HTTP communication with PostHog's /capture endpoint.

Event Whitelisting and Filtering

Agentsview implements strict event filtering to limit data transmission. The allowedEventOptions() function builds a whitelist of permitted events passed as PostHogOptions to the underlying client.

Currently, only the daemon_active event (constant EventDaemonActive) is authorized for transmission. This restrictive approach ensures the telemetry system cannot accidentally transmit unintended event types, maintaining compliance with privacy expectations.

Periodic Heartbeat Transmission

After server initialization, startTelemetryPings (lines 95–115 in cmd/agentsview/main.go) schedules a background goroutine with a telemetryPingInterval of 24 hours. Each tick invokes reporter.CaptureDaemonActive, which constructs the event payload and forwards it through the PostHog client.

The periodic nature provides operational insights into active installations without high-frequency data collection that might impact performance or bandwidth.

Graceful Shutdown and Event Flushing

During application termination, the deferred rep.Close() call in main.go triggers the reporter's shutdown sequence. This method flushes any pending events to PostHog's ingestion API before the process exits, preventing data loss during graceful shutdowns or rolling updates.

Implementation Examples

Creating a Reporter Instance

When building custom tooling or testing the telemetry pipeline, instantiate the reporter using the same pattern as the production binary:

import (
    "go.kenn.io/agentsview/internal/telemetry"
)

func makeReporter(dataDir, version, commit string) *telemetry.Reporter {
    // Returns a disabled reporter if telemetry is off or tests are running.
    return telemetry.NewReporterOrDisabled(telemetry.Options{
        DataDir: dataDir,
        Version: version,
        Commit:  commit,
    })
}

Sending Manual Daemon-Active Events

For debugging or custom heartbeat implementations, manually trigger the whitelisted event:

ctx := context.Background()
rep := makeReporter("/path/to/data", "v1.2.3", "abcd1234")
defer rep.Close()

if rep.Enabled() {
    // Same event the periodic ticker sends.
    if err := rep.CaptureDaemonActive(ctx); err != nil {
        log.Printf("failed to send telemetry: %v", err)
    }
}

Integrating Periodic Pings

The production server implementation combines initialization with background scheduling:

// Inside cmd/agentsview/main.go
telemetryReporter := telemetry.NewReporterOrDisabled(telemetry.Options{
    DataDir: cfg.DataDir,
    Version: version,
    Commit:  commit,
})
defer telemetryReporter.Close()

go startTelemetryPings(ctx, telemetryReporter) // see startTelemetryPings()

Summary

• Configuration: Enable telemetry via AGENTSVIEW_TELEMETRY_ENABLED; automatically disabled during go test runs.
• Identity Management: Persistent install IDs stored in the data directory track unique deployments anonymously.
• Event Filtering: Only daemon_active events pass through the whitelist, enforced by allowedEventOptions() in internal/telemetry/telemetry.go.
• Transmission Schedule: The startTelemetryPings function in cmd/agentsview/main.go schedules daily heartbeats using a 24-hour ticker.
• Shutdown Safety: The Close() method ensures pending events flush to PostHog before process termination.

Frequently Asked Questions

How do I disable telemetry reporting in agentsview?

Set the environment variable AGENTSVIEW_TELEMETRY_ENABLED=false (or GENERIC_TELEMETRY_ENABLED=false) before starting the binary. When disabled, telemetry.NewReporterOrDisabled returns a no-op implementation that performs no network operations. The system also automatically disables telemetry when detecting test execution via go test.

What specific data does agentsview transmit to PostHog?

The system transmits only the daemon_active event containing anonymized metadata: the persistent install ID, application version, git commit hash, and source label (daemon). No user data, agent configurations, or operational logs leave your infrastructure.

How often does agentsview report telemetry to PostHog?

The startTelemetryPings function schedules events every 24 hours using telemetryPingInterval. Each tick calls CaptureDaemonActive, transmitting a single heartbeat event to indicate the daemon remains active.

Where does agentsview store the telemetry install ID?

The install ID persists in a file named telemetry-install-id within the configured data directory (opts.DataDir). This file allows the reporter to maintain consistent anonymous identification across service restarts without requiring machine-specific identifiers or registry entries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}