npm package: @flisk/analyze-tracking
Description: Analyzes tracking code in a project and generates data schemas
Author: Sameen Karim
Latest version: 0.9.2

# @flisk/analyze-tracking

Automatically document your analytics setup by analyzing tracking code and generating data schemas from tools like Segment, Amplitude, Mixpanel, and more 🚀

[![NPM version](https://img.shields.io/npm/v/@flisk/analyze-tracking.svg)](https://www.npmjs.com/package/@flisk/analyze-tracking) [![Tests](https://github.com/fliskdata/analyze-tracking/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/fliskdata/analyze-tracking/actions/workflows/tests.yml)


## Why Use @flisk/analyze-tracking?
📊 **Understand Your Tracking** – Effortlessly analyze your codebase for `track` calls so you can see all your analytics events, properties, and triggers in one place. No more guessing what's being tracked!

🔍 **Auto-Document Events** – Generates a complete YAML schema that captures all events and properties, including where they're implemented in your codebase.

🕵️‍♂️ **Track Changes Over Time** – Easily spot unintended changes or ensure your analytics setup remains consistent across updates.

📚 **Populate Data Catalogs** – Automatically generate structured documentation that can help feed into your data catalog, making it easier for everyone to understand your events.


## Quick Start

Run without installation! Just use:

```sh
npx @flisk/analyze-tracking /path/to/project [options]
```

### Key Options
- `-g, --generateDescription`: Generate descriptions of fields (default: `false`)
- `-p, --provider <provider>`: Specify a provider (options: `openai`, `gemini`)
- `-m, --model <model>`: Specify a model (ex: `gpt-4.1-nano`, `gpt-4o-mini`, `gemini-2.0-flash-lite-001`)
- `-o, --output <output_file>`: Name of the output file (default: `tracking-schema.yaml`)
- `-c, --customFunction <function_signature>`: Specify the signature of your custom tracking function (see [instructions here](#custom-functions))
- `--format <format>`: Output format, either `yaml` (default) or `json`. If an invalid value is provided, the CLI will exit with an error.
- `--stdout`: Print the output to the terminal instead of writing to a file (works with both YAML and JSON)

🔑&nbsp; **Important:** If you are using `generateDescription`, you must set the appropriate credentials for the LLM provider you are using as an environment variable. OpenAI uses `OPENAI_API_KEY` and Google Vertex AI uses `GOOGLE_APPLICATION_CREDENTIALS`.


### Custom Functions

If you have your own in-house tracker or a wrapper function that calls other tracking libraries, you can specify the function signature with the `-c` or `--customFunction` option.

#### Standard Custom Function Format

Your function signature should be in the following format:
```js
yourCustomTrackFunctionName(EVENT_NAME, PROPERTIES, customFieldOne, customFieldTwo)
```

- `EVENT_NAME` is the name of the event you are tracking. It should be a string or a pointer to a string. This is required.
- `PROPERTIES` is an object of properties for that event. It should be an object / dictionary. This is optional.
- Any additional parameters are other fields you are tracking. They can be of any type. The names you provide for these parameters will be used as the property names in the output.


For example, if your function has a userId parameter at the beginning, followed by the event name and properties, you would pass in the following:

```js
yourCustomTrackFunctionName(userId, EVENT_NAME, PROPERTIES)
```

If your function follows the standard format `yourCustomTrackFunctionName(EVENT_NAME, PROPERTIES)`, you can simply pass in `yourCustomTrackFunctionName` to `--customFunction` as a shorthand.

#### Method-Name-as-Event Format

For tracking patterns where the method name itself is the event name (e.g., `yourClass.yourEventName({...})`), use the special `EVENT_NAME` placeholder in the method position:

```js
yourClass.EVENT_NAME(PROPERTIES)
```

This pattern tells the analyzer that:
- `yourClass` is the object name to match
- The method name after the dot (e.g., `viewItemList`, `addToCart`) is the event name
- `PROPERTIES` is the properties object (defaults to the first argument if not specified)

**Example:**
```typescript
// Code in your project:
yourClass.viewItemList({ items: [...] });
yourClass.addToCart({ item: {...}, value: 100 });
yourClass.purchase({ userId: '123', value: 100 });

// Command:
npx @flisk/analyze-tracking /path/to/project --customFunction "yourClass.EVENT_NAME(PROPERTIES)"
```

This will detect:
- Event: `viewItemList` with properties from the first argument
- Event: `addToCart` with properties from the first argument
- Event: `purchase` with properties from the first argument

_**Note:** This pattern is currently only supported for JavaScript and TypeScript code._

#### Multiple Custom Functions

You can also pass in multiple custom function signatures by passing in the `--customFunction` option multiple times or by passing in a space-separated list of function signatures.

```sh
npx @flisk/analyze-tracking /path/to/project --customFunction "yourFunc1" --customFunction "yourFunc2(userId, EVENT_NAME, PROPERTIES)"
npx @flisk/analyze-tracking /path/to/project -c "yourFunc1" "yourFunc2(userId, EVENT_NAME, PROPERTIES)"
npx @flisk/analyze-tracking /path/to/project -c "yourClass.EVENT_NAME(PROPERTIES)" "customTrack(EVENT_NAME, PROPERTIES)"
```


## What's Generated?
A clear YAML schema that shows where your events are tracked, their properties, and more.
Here's an example:

```yaml
version: 1
source:
  repository: <repository_url>
  commit: <commit_sha>
  timestamp: <commit_timestamp>
events:
  <event_name>:
    description: <ai_generated_description>
    implementations:
      - description: <ai_generated_description>
        path: <path_to_file>
        line: <line_number>
        function: <function_name>
        destination: <platform_name>
    properties:
      <property_name>:
        description: <ai_generated_description>
        type: <property_type>
```

Use this to understand where your events live in the code and how they're being tracked.

Your LLM of choice is used for generating descriptions of events, properties, and implementations.

See [schema.json](schema.json) for a JSON Schema of the output.


## Supported tracking libraries & languages

| Library | JavaScript/TypeScript | Python | Ruby | Go | Swift |
|---------|:---------------------:|:------:|:----:|:--:|:--:|
| Google Analytics   | ✅ | ❌ | ❌ | ❌ | ✅ |
| Google Tag Manager | ✅ | ❌ | ❌ | ❌ | ✅ |
| Segment            | ✅ | ✅ | ✅ | ✅ | ✅ |
| Mixpanel           | ✅ | ✅ | ✅ | ✅ | ✅ |
| Amplitude          | ✅ | ✅ | ❌ | ✅ | ✅ |
| Rudderstack        | ✅ | ✅ | ✳️ | ✳️ | ✅ |
| mParticle          | ✅ | ❌ | ❌ | ❌ | ✅ |
| PostHog            | ✅ | ✅ | ✅ | ✅ | ✅ |
| Pendo              | ✅ | ❌ | ❌ | ❌ | ✅ |
| Heap               | ✅ | ❌ | ❌ | ❌ | ✅ |
| Snowplow           | ✅ | ✅ | ✅ | ✅ | ❌ |
| Datadog RUM        | ✅ | ❌ | ❌ | ❌ | ❌ |
| Custom Function    | ✅ | ✅ | ✅ | ✅ | ✅ |

✳️ Rudderstack's SDKs often use the same format as Segment, so Rudderstack events may be detected as Segment events.


## SDKs for supported libraries

<details>
  <summary>Google Analytics</summary>

  **JavaScript/TypeScript**
  ```js
  gtag('event', '<event_name>', {
    '<property_name>': '<property_value>'
  });
  ```

  **Swift**
  ```swift
  Analytics.logEvent("<event_name>", parameters: [
    "<property_name>": "<property_value>"
  ])
  ```
</details>

<details>
  <summary>Google Tag Manager</summary>

  **JavaScript/TypeScript**
  ```js
  dataLayer.push({
    event: '<event_name>',
    '<property_name>': '<property_value>'
  });

  // Or via window
  window.dataLayer.push({
    event: '<event_name>',
    '<property_name>': '<property_value>'
  });
  ```

  **Swift**
  ```swift
  dataLayer.push(["event": "<event_name>", "<property_name>": "<property_value>"])
  ```
</details>

<details>
  <summary>Segment</summary>

  **JavaScript/TypeScript**
  ```js
  analytics.track('<event_name>', {
    '<property_name>': '<property_value>'
  });
  ```

  **Python**
  ```python
  analytics.track('<event_name>', {
    '<property_name>': '<property_value>'
  })
  ```

  **Ruby**
  ```ruby
  Analytics.track(
    event: '<event_name>',
    properties: {
      '<property_name>': '<property_value>'
    }
  )
  ```

  **Go**
  ```go
  client.Enqueue(analytics.Track{
    UserId: "user-id",
    Event:  "<event_name>",
    Properties: analytics.NewProperties().
      Set("<property_name>", "<property_value>"),
  })
  ```

  **Swift**
  ```swift
  analytics.track(name: "<event_name>", properties: TrackProperties("<property_name>": "<property_value>"))
  ```
</details>

<details>
  <summary>Mixpanel</summary>

  **JavaScript/TypeScript**
  ```js
  mixpanel.track('<event_name>', {
    '<property_name>': '<property_value>'
  });
  ```

  **Python**
  ```python
  mixpanel.track('<event_name>', {
    '<property_name>': '<property_value>'
  })
  ```

  **Ruby**
  ```ruby
  tracker.track('<distinct_id>', '<event_name>', {
    '<property_name>': '<property_value>'
  })
  ```

  **Go**
  ```go
  ctx := context.Background()
  mp := mixpanel.NewApiClient("YOUR_PROJECT_TOKEN")
  mp.Track(ctx, []*mixpanel.Event{
    mp.NewEvent("<event_name>", "", map[string]any{}{
      "<property_name>": "<property_value>",
    }),
  })
  ```

  **Swift**
  ```swift
  Mixpanel.mainInstance().track(event: "<event_name>", properties: [
    "<property_name>": "<property_value>"
  ])
  ```
</details>

<details>
  <summary>Amplitude</summary>

  **JavaScript/TypeScript**
  ```js
  amplitude.track('<event_name>', {
    <event_parameters>
  });
  ```

  **Python**
  ```python
  client.track(
    BaseEvent(
      event_type="<event_name>",
      user_id="<user_id>",
      event_properties={
        "<property_name>": "<property_value>",
      },
    )
  )
  ```

  **Go**
  ```go
  client.Track(amplitude.Event{
    UserID:    "<user_id>",
    EventType: "<event_name>",
    EventProperties: map[string]any{}{
      "<property_name>": "<property_value>",
    },
  })
  ```

  **Swift**
  ```swift
  amplitude.track(
    eventType: "<event_name>",
    eventProperties: ["<property_name>": "<property_value>"]
  )
  ```
</details>

<details>
  <summary>Rudderstack</summary>

  **JavaScript/TypeScript**
  ```js
  rudderanalytics.track('<event_name>', {
    <event_parameters>
  });
  ```

  **Python**
  ```python
  rudder_analytics.track('<event_name>', {
    '<property_name>': '<property_value>'
  })
  ```

  **Ruby**
  ```ruby
  analytics.track(
    user_id: '<user_id>',
    event: '<event_name>',
    properties: {
      '<property_name>': '<property_value>'
    }
  )
  ```

  **Go**
  ```go
  client.Enqueue(analytics.Track{
    UserId: "<user_id>",
    Event:  "<event_name>",
    Properties: analytics.NewProperties().
      Set("<property_name>", "<property_value>"),
  })
  ```

  **Swift**
  ```swift
  RSClient.sharedInstance()?.track("<event_name>", properties: [
    "<property_name>": "<property_value>"
  ])
  ```
</details>

<details>
  <summary>mParticle</summary>

  **JavaScript/TypeScript**
  ```js
  mParticle.logEvent('<event_name>', mParticle.EventType.<event_type>, {
    '<property_name>': '<property_value>'
  });
  ```

  **Swift**
  ```swift
  let event = MPEvent(name: "<event_name>", type: .other)
  event.customAttributes = [
    "<property_name>": "<property_value>"
  ]
  MParticle.sharedInstance().logEvent(event)
  ```
</details>

<details>
  <summary>PostHog</summary>

  **JavaScript/TypeScript**
  ```js
  posthog.capture('<event_name>', {
    '<property_name>': '<property_value>'
  });
  ```

  **Python**
  ```python
  posthog.capture('distinct_id', '<event_name>', {
    '<property_name>': '<property_value>'
  })
  # Or
  posthog.capture(
    'distinct_id',
    event='<event_name>',
    properties={
      '<property_name>': '<property_value>'
    }
  )
  ```

  **Ruby**
  ```ruby
  posthog.capture({
    distinct_id: '<distinct_id>',
    event: '<event_name>',
    properties: {
      '<property_name>': '<property_value>'
    }
  })
  ```

  **Go**
  ```go
  client.Enqueue(posthog.Capture{
    DistinctId: "<distinct_id>",
    Event:      "<event_name>",
    Properties: posthog.NewProperties().
      Set("<property_name>", "<property_value>"),
  })
  ```

  **Swift**
  ```swift
  PostHogSDK.shared.capture("<event_name>", properties: [
    "<property_name>": "<property_value>"
  ])
  ```
</details>

<details>
  <summary>Pendo</summary>

  **JavaScript/TypeScript**
  ```js
  pendo.track('<event_name>', {
    <event_parameters>
  });
  ```

  **Python**
  ```python
  pendo.track('<event_name>', {
    '<property_name>': '<property_value>'
  })
  ```

  **Swift**
  ```swift
  PendoManager.shared().track("<event_name>", properties: [
    "<property_name>": "<property_value>"
  ])
  ```
</details>

<details>
  <summary>Heap</summary>

  **JavaScript/TypeScript**
  ```js
  heap.track('<event_name>', {
    <event_parameters>
  });
  ```

  **Python**
  ```python
  heap.track('<event_name>', {
    '<property_name>': '<property_value>'
  })
  ```

  **Swift**
  ```swift
  Heap.shared.track("<event_name>", properties: [
    "<property_name>": "<property_value>"
  ])
  ```
</details>

<details>
  <summary>Datadog RUM</summary>

  **JavaScript/TypeScript**
  ```js
  datadogRum.addAction('<event_name>', {
    '<property_name>': '<property_value>'
  });

  // Or via window
  window.DD_RUM.addAction('<event_name>', {
    '<property_name>': '<property_value>'
  });

  // Or via global DD_RUM
  DD_RUM.addAction('<event_name>', {
    '<property_name>': '<property_value>'
  });
  ```
</details>

<details>
  <summary>Snowplow (Structured Events)</summary>

  **JavaScript/TypeScript**
  ```js
  tracker.track(buildStructEvent({
    action: '<event_name>',
    category: '<category>',
    label: '<label>',
    property: '<property>',
    value: <value>
  }));
  ```

  **Python**
  ```python
  tracker.track(StructuredEvent(
    action="<event_name>",
    category="<category>",
    label="<label>",
    property_="<property>",
    value=<value>,
  ))
  ```

  **Ruby**
  ```ruby
  tracker.track_struct_event(
    action: '<event_name>',
    category: '<category>',
    label: '<label>',
    property: '<property>',
    value: <value>
  )
  ```

  **Go**
  ```go
  tracker.TrackStructEvent(sp.StructuredEvent{
		Action:   sp.NewString("<event_name>"),
		Category: sp.NewString("<category>"),
		Label:    sp.NewString("<label>"),
		Property: sp.NewString("<property>"),
		Value:    sp.NewFloat64(<value>),
	})
  ```
</details>


## Contribute
We're actively improving this package. Found a bug? Have a feature request? Open an issue or submit a pull request!

[![Slack](https://img.shields.io/badge/Join%20Us%20on%20Slack-Flisk%20Community-611f69.svg?logo=slack)](https://join.slack.com/t/fliskcommunity/shared_invite/zt-354hesfnm-BbNzveERo9C4JwVQEWvXoA)