# Agentsview Telemetry Reporting Mechanism Using PostHog: Complete Implementation Guide

> Learn how Agentsview uses PostHog for telemetry reporting. This guide details implementation including install IDs, event whitelisting, and heartbeat pings.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-06-20

---

**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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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 `PostHogOption`s 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`](https://github.com/kenn-io/agentsview/blob/main/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`](https://github.com/kenn-io/agentsview/blob/main/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:

```go
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:

```go
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:

```go
// 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`](https://github.com/kenn-io/agentsview/blob/main/internal/telemetry/telemetry.go).
- **Transmission Schedule**: The `startTelemetryPings` function in [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/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.