Add telemetry to your SDK with SDK hooks and Posthog

Prerequisites

• You will need a Posthog account (If you don’t have one, you can sign up here )

Overview

This guide will walk you through adding telemetry to a TypeScript SDK using SDK hooks and the Posthog Node SDK.

SDK hooks are a way to inject custom actions at various points in the SDK’s execution.

You can inject custom actions at the following points in the SDK’s execution:

• On SDK Initialization
• Before a request is executed
• After a successful response
• After an error response

Adding the Posthog SDK to your project

To add the Posthog SDK to your project, you will need to add the dependency to your Speakeasy SDK’s gen.yaml file under the dependancies section:

After adding the dependency, the Posthog SDK will be included in your projects package.json file every time you generate your SDK.

Adding your first SDK hook

Now that you have the Posthog SDK included in your project, you can start adding SDK hooks to your SDK.

First, create a new file in the src/hooks directory, and name it telemetry_hooks.ts.

In this file you will need to import the hook types for each hook you want to use, as well as the PostHog SDK and initialize the PostHog SDK with your API Key. I will be using all four of the hooks in this guide, but you can choose which hooks you want to use.

Next you can create a class that will hold your hooks. Our class will be TelemetryHooks and our first hook will be an On SDK Initialization hook.

Below is the start of our TelemetryHooks class. This class will hold all of our telemetry hooks.

This hook allows us to inject custom actions and capture an SDK Init event to Posthog at the time the SDK is initialized.

Here are the key points to the capture method outlined below:

• distinctId: A distinctId can be provided, serving as a unique identifier for either a user or a session. This is particularly useful for tracking recurring events across different sessions, which can aid in identifying and troubleshooting issues.
• event: The name of the event is specified to facilitate easier sorting and analysis within Posthog.
• properties: An arbitrary set of properties; extra information relevant to the event. Here the contents of the opts parameter are added to the event as properties. This allows for detailed tracking of the initialization parameters.

Lastly Posthog’s SDKs are asynchronous, so we need to shutdown the SDK after we are done, ensuring events are flushed out before the process ends.

Now that we have our TelemetryHooks class, we can add the remainder of the hooks.

The structure of the remaining hooks is the same, We just supply a distinctId, an event, and properties for each hook.

Once all the hooks are implemented, you can now use the TelemetryHooks class in your SDK.

in the src/hooks/registration.ts, you simply need to import the class from the file you created the hooks in, and register them following the directions in the comment.

You can now regenerate your SDK and use the new hooks.

Running API calls using this SDK will surface events up to Posthog.

And you can review all the details in Posthog.

You can review all the code outlined in this guide in the SDK Hooks  repository.