> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learningcommons.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Telemetry

> Understand what telemetry the Learning Commons TypeScript SDK collects, how to configure it, and how to opt out.

The TypeScript SDK collects telemetry to help us improve evaluator quality, identify edge cases, and optimize performance.

## What we collect

**Telemetry is enabled by default** and sends anonymous performance and metadata:

* Performance metrics (latency, token usage)
* Metadata (evaluator type, grade, SDK version)

<Note>
  Your text input is **not** collected by default. You can opt into our collecting using `recordInputs: true`. See [Enable input text collection](#enable-input-text-collection).
</Note>

We **never** collect your API keys — only an anonymous identifier is used.

## Example telemetry event

```json theme={null}
{
  "timestamp": "2026-02-05T19:30:00.000Z",
  "sdk_version": "0.1.0",
  "evaluator_type": "vocabulary",
  "grade": "3",
  "status": "success",
  "latency_ms": 3500,
  "text_length_chars": 456,
  "provider": "openai:gpt-4o-2024-11-20 + google:gemini-2.5-pro",
  "token_usage": {
    "input_tokens": 650,
    "output_tokens": 350
  },
  "metadata": {
    "stage_details": [
      {
        "stage": "background_knowledge",
        "provider": "openai:gpt-4o-2024-11-20",
        "latency_ms": 1200,
        "token_usage": {
          "input_tokens": 250,
          "output_tokens": 150
        }
      },
      {
        "stage": "complexity_evaluation",
        "provider": "google:gemini-2.5-pro",
        "latency_ms": 2300,
        "token_usage": {
          "input_tokens": 400,
          "output_tokens": 200
        }
      }
    ]
  }
}
```

## Field reference

| Field                    | Description                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `timestamp`              | ISO 8601 timestamp when evaluation started                                |
| `sdk_version`            | Version of the SDK (e.g., `"0.1.0"`)                                      |
| `evaluator_type`         | Which evaluator ran (e.g., `"vocabulary"`, `"sentence-structure"`)        |
| `grade`                  | Grade level evaluated (e.g., `"5"`, `"K"`)                                |
| `status`                 | Evaluation outcome: `"success"` or `"error"`                              |
| `error_code`             | Error type if status is `"error"` (e.g., `"Error"`, `"TypeError"`)        |
| `latency_ms`             | Total evaluation time in milliseconds                                     |
| `text_length_chars`      | Length of input text in characters                                        |
| `provider`               | LLM provider(s) used (e.g., `"openai:gpt-4o"`, `"google:gemini-2.5-pro"`) |
| `token_usage`            | Total tokens consumed (input and output)                                  |
| `input_text`             | The text being evaluated — only included if `recordInputs: true`          |
| `metadata.stage_details` | Per-stage breakdown for multi-stage evaluators (optional)                 |

## Configuration

### Default (anonymous)

Telemetry is on by default with no configuration required:

```typescript theme={null}
const evaluator = new VocabularyEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  // telemetry: true (default — anonymous)
});
```

### Partner with us (authenticated)

Provide a partner key to help us support your specific use case and collaborate more directly:

```typescript theme={null}
const evaluator = new VocabularyEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  partnerKey: process.env.LEARNING_COMMONS_PARTNER_KEY!, // Contact us for a key
});
```

[Reach out to get a partner key](mailto:support@learningcommons.org) ↗

### Disable telemetry completely

```typescript theme={null}
const evaluator = new VocabularyEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  telemetry: false, // No data sent
});
```

### Enable input text collection

```typescript theme={null}
const evaluator = new VocabularyEvaluator({
  googleApiKey: process.env.GOOGLE_API_KEY!,
  openaiApiKey: process.env.OPENAI_API_KEY!,
  telemetry: {
    enabled: true,
    recordInputs: true, // Also send input text with telemetry
  },
});
```