# How to Configure gstack Telemetry and What Data It Collects

> Learn how to configure gstack telemetry to collect operational events like skill lifecycles and CDP calls without sensitive data. Explore the lightweight, opt-out system and its logged JSONL data.

- Repository: [Garry Tan/gstack](https://github.com/garrytan/gstack)
- Tags: how-to-guide
- Published: 2026-05-15

---

**gstack telemetry is a lightweight, opt-out system that logs high-level operational events—such as domain skill lifecycles and CDP method calls—to a local JSONL file, deliberately excluding all skill bodies, user arguments, and generated text.**

gstack, an open-source project available at garrytan/gstack, implements a minimal telemetry subsystem designed for transparency and user control. The **gstack telemetry** architecture records discrete operational signals to help improve the tool while enforcing strict privacy boundaries that prevent the capture of sensitive content. All configuration logic and data schemas are defined in TypeScript within the [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts) module.

## Configuring gstack Telemetry

### Environment Variable Overrides

The fastest way to disable telemetry is by setting the `GSTACK_TELEMETRY_OFF` environment variable. When set to `1`, the `logTelemetry` function in [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts) immediately becomes a no-op, preventing any disk writes or network calls for the duration of the process.

```bash

# Disable for the current shell session

export GSTACK_TELEMETRY_OFF=1
bun run gstack

# Enable explicitly (default behavior)

GSTACK_TELEMETRY_OFF=0 bun run gstack

```

The module checks `process.env.GSTACK_TELEMETRY_OFF` on each invocation, with a test helper `_resetTelemetryCache` available to clear cached values during testing.

### Persistent Configuration with gstack-config

For permanent settings across sessions, use the `gstack-config` CLI helper. This tool writes the selected tier to a state file located at `~/.gstack/.telemetry`. The system supports three distinct tiers:

- **off**: Completely disables event collection; `logTelemetry` returns immediately without action.
- **anonymous**: Stores all events locally in `~/.gstack/analytics/browse-telemetry.jsonl` without network transmission.
- **community**: Retains local storage and additionally triggers periodic upload to remote analytics services via the telemetry-sync command.

```bash

# Set tier via CLI

gstack-config set telemetry off
gstack-config set telemetry anonymous
gstack-config set telemetry community

```

The helper resolves the gstack home directory using `resolveGstackHome` from [`browse/src/config.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/config.ts), which checks `$GSTACK_HOME` before defaulting to `$HOME/.gstack`.

### Telemetry File Storage

All telemetry records append to `~/.gstack/analytics/browse-telemetry.jsonl`. The path is constructed dynamically from the gstack home directory, ensuring users retain full ownership to inspect, delete, or back up their data. Writes are performed asynchronously in a fire-and-forget manner; any disk errors (e.g., permission denied or disk full) are silently swallowed to guarantee that telemetry collection never crashes the main application process.

## What Data gstack Telemetry Collects

### Event Structure and Common Fields

Every telemetry entry is a single line of JSON (JSONL) containing at minimum an `event` string and an ISO-8601 `ts` timestamp. As implemented in [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts), the system records only high-level operational metadata—never skill implementations, command arguments, or conversation history.

### Domain Skill Lifecycle Events

These events are emitted from [`browse/src/domain-skill-commands.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/domain-skill-commands.ts) to track skill management operations:

- **domain_skill_saved**: Triggered when a skill is persisted, containing fields `{ host, scope, state, bytes }`—the origin host, scope (`project` or `global`), resulting state, and byte size of the body.
- **domain_skill_state_changed**: Records state transitions with `{ host, from_state, to_state }`, such as quarantined to active.
- **domain_skill_save_blocked**: Logs content filter rejections via `{ host, reason }`.
- **domain_skill_fired**: Captures invocation events with `{ host, source, version }`, indicating whether the trigger was `agent` or `human`.

### Chrome DevTools Protocol (CDP) Events

The system monitors CDP usage for security auditing and performance analysis:

- **cdp_method_called**: Successful calls include `{ domain, method, allowed, scope }`.
- **cdp_method_denied**: Blocked calls log `{ domain, method }` when the allow-list rejects a request.
- **cdp_method_lock_acquire_ms**: Performance metrics capturing lock acquisition latency via `{ domain, method, ms }`.

### Privacy Guarantees

The telemetry system explicitly avoids collecting sensitive data. According to the source code in [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts), the following are **never** recorded:
- Skill body content or source code
- User-provided command-line arguments or inputs
- Agent-generated text or conversation transcripts
- Authentication credentials or personal identifiers

## Working with Telemetry Programmatically

### Logging Custom Events

Developers can utilize the same internal API to record custom high-level events:

```typescript
import { logTelemetry } from './browse/src/telemetry';

// This writes only if telemetry is enabled
logTelemetry({
  event: 'cdp_method_called',
  domain: 'Network',
  method: 'enable',
  allowed: true,
  scope: 'session',
});

```

### Testing with Temporary Storage

During automated testing, redirect telemetry output and reset the configuration cache:

```typescript
process.env.GSTACK_HOME = '/tmp/gstack-test-home';
process.env.GSTACK_TELEMETRY_OFF = '0'; // Ensure enabled for test

// Import after setting environment
import { logTelemetry, _resetTelemetryCache } from './browse/src/telemetry';

_resetTelemetryCache(); // Clear any cached config
logTelemetry({
  event: 'domain_skill_saved',
  host: 'example.com',
  scope: 'project',
  state: 'active',
  bytes: 123
});

```

## Summary

- **gstack telemetry** is disabled by setting `GSTACK_TELEMETRY_OFF=1` or using `gstack-config set telemetry off`, with preferences stored in `~/.gstack/.telemetry`.
- Events append to `~/.gstack/analytics/browse-telemetry.jsonl` in JSONL format, capturing only metadata like `domain_skill_saved` and `cdp_method_called`.
- The system strictly excludes skill bodies, user arguments, and generated text, recording only anonymous operational signals such as timestamps, host origins, and byte counts.
- Runtime configuration is evaluated in [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts), with the cache resettable via `_resetTelemetryCache` for isolated testing scenarios.

## Frequently Asked Questions

### How do I completely disable gstack telemetry?

Set the environment variable `GSTACK_TELEMETRY_OFF=1` before executing any command, or run `gstack-config set telemetry off` to write the preference permanently to `~/.gstack/.telemetry`. When disabled, the `logTelemetry` function in [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts) becomes a no-op, ensuring no data is written to disk or transmitted over the network.

### What is the difference between anonymous and community telemetry tiers?

The **anonymous** tier stores all events locally in `~/.gstack/analytics/browse-telemetry.jsonl` without any network activity, while the **community** tier permits the telemetry-sync command to upload aggregated data to remote analytics servers. Both tiers collect identical event schemas; only the data transmission behavior differs.

### Does gstack telemetry record the content of my skills or prompts?

No. The implementation in [`browse/src/telemetry.ts`](https://github.com/garrytan/gstack/blob/main/browse/src/telemetry.ts) deliberately excludes skill bodies, user-provided arguments, and agent-generated text from all event payloads. For example, the `domain_skill_saved` event records metadata such as the host, scope, state, and byte size, but never the actual skill implementation or content.

### Where can I inspect the telemetry data that has been collected?

All telemetry records are stored in `~/.gstack/analytics/browse-telemetry.jsonl` (or `$GSTACK_HOME/analytics/browse-telemetry.jsonl` if the home directory is customized). The file uses JSON Lines format, with one JSON object per line, allowing you to view entries with standard tools like `cat`, parse them with `jq`, or delete the file entirely to clear history.