Octaviaflow Telemetry Collector

JavaScript telemetry collection tooling for octaviaflow projects

Overview

Octaviaflow Telemetry Collector is a powerful analytics tool that captures anonymized usage data from JavaScript/TypeScript projects. It supports multiple data collection scopes including NPM dependencies, JSX components, JavaScript functions, and Web Components.

Key Features

• File-based Storage: Store telemetry data in JSON files ready for MongoDB Atlas import
• Multiple Collection Scopes: NPM, JSX, JavaScript, and Web Components
• Privacy-First: Anonymized data collection with configurable allowlists
• MongoDB Ready: Generated files are formatted for direct MongoDB import
• CLI Tool: Easy-to-use command-line interface

Installation

npm install @octaviaflow/telemetry-collector

Quick Start

1. Create Configuration File

Create a telemetry.yml file in your project root:

# yaml-language-server: $schema=https://unpkg.com/@octaviaflow/telemetry-config-schema@1/dist/config.schema.json
version: 1
projectId: 'my-awesome-project'
name: 'my-awesome-project'
storage:
  type: 'file'
  file:
    directory: './telemetry-logs'
    fileNamePattern: 'octaviaflow-telemetry-{timestamp}.json'
    maxFileSizeMB: 10
collect:
  npm:
    dependencies:
  jsx:
    elements:
      allowedAttributeNames: ['size', 'variant']
      allowedAttributeStringValues: ['small', 'medium', 'large']

2. Run Collection

# Basic usage
npx octaviaflow-telemetry --config ./telemetry.yml

# With verbose output
npx octaviaflow-telemetry --config ./telemetry.yml --verbose

# Dry run (no data stored)
npx octaviaflow-telemetry --config ./telemetry.yml --dry-run

3. Import to MongoDB Atlas

After collection, import the generated JSON files to MongoDB Atlas:

mongoimport --uri "mongodb+srv://user:[email protected]/database" \
  --collection telemetry \
  --file ./telemetry-logs/octaviaflow-telemetry-2025-01-01T10-00-00-000Z.json

Configuration

Storage Options

File Storage (Current)

storage:
  type: 'file'
  file:
    directory: './telemetry-logs'           # Directory to store files
    fileNamePattern: 'octaviaflow-telemetry-{timestamp}.json'  # File naming pattern
    maxFileSizeMB: 10                       # Max file size before rotation
    compress: false                         # Enable compression (future)

MongoDB Storage (Future)

storage:
  type: 'mongodb'
  mongodb:
    connectionString: 'mongodb+srv://user:[email protected]'
    database: 'telemetry'
    collection: 'metrics'

Collection Scopes

NPM Dependencies

Captures package dependency information:

collect:
  npm:
    dependencies:  # Captures all dependencies and versions

JSX Components

Captures React component usage:

collect:
  jsx:
    elements:
      allowedAttributeNames:
        - 'size'
        - 'variant'
        - 'color'
      allowedAttributeStringValues:
        - 'small'
        - 'medium'
        - 'large'

JavaScript Functions

Captures function calls and arguments:

collect:
  js:
    tokens:  # Captures imported tokens
    functions:
      allowedArgumentStringValues:
        - 'debug'
        - 'info'
        - 'error'

Web Components

Captures Web Component usage:

collect:
  wc:
    elements:
      allowedAttributeNames:
        - 'type'
        - 'disabled'
      allowedAttributeStringValues:
        - 'button'
        - 'submit'

CLI Options

octaviaflow-telemetry [options]

Options:
  -c, --config <path>  Path to telemetry configuration file (default: "./telemetry.yml")
  -v, --verbose        Enable verbose logging
  --dry-run           Perform a dry run without storing data
  -h, --help          Display help for command
  --version           Display version number

Data Format

Generated JSON files contain telemetry data in MongoDB-ready format:

{
  "_id": "507f1f77bcf86cd799439011",
  "timestamp": "2025-01-01T10:00:00.000Z",
  "projectId": "my-awesome-project",
  "scope": "jsx",
  "metric": "jsx.element",
  "data": {
    "elements": [
      {
        "name": "Button",
        "attributes": { "size": "large", "variant": "primary" },
        "moduleSpecifier": "@octaviaflow/ui"
      }
    ]
  },
  "metadata": {
    "collectionTimestamp": "2025-01-01T10:00:00.000Z",
    "storageType": "file",
    "collectionMethod": "jsx-analysis"
  }
}

Integration with Package

Add telemetry collection to your package's postinstall script:

{
  "scripts": {
    "postinstall": "octaviaflow-telemetry --config ./telemetry.yml"
  }
}

Privacy and Data Collection

• Anonymized by Default: All sensitive data is anonymized unless specifically allowlisted
• Configurable Collection: Only collect data you explicitly configure
• Local Storage: Data is stored locally in files, giving you full control
• No External Calls: No data is sent to external servers automatically

MongoDB Atlas Import

Prepare Data for Import

The collector can prepare all collected data for MongoDB import:

import { FileStorage } from '@octaviaflow/telemetry-collector';

const storage = new FileStorage({ directory: './telemetry-logs' });
const importFile = await storage.prepareForMongoImport('./mongodb-ready.json');
console.log('Ready for import:', importFile);

Import Commands

# Import single file
mongoimport --uri "your-connection-string" \
  --collection telemetry \
  --file ./telemetry-logs/octaviaflow-telemetry-2025-01-01T10-00-00-000Z.json

# Import all files
for file in ./telemetry-logs/*.json; do
  mongoimport --uri "your-connection-string" \
    --collection telemetry \
    --file "$file"
done

Related Packages

• @octaviaflow/telemetry-config-schema - Configuration schema and validation
• @octaviaflow/telemetry-attributes - Telemetry attribute definitions

License

MIT © octaviaflow