Generate SDK Telemetry with Speakeasy
An API is no different from any other product. You need to understand how it’s being used before you start planning changes; good data leads to good decisions.
And yet, many companies don’t have telemetry on which users are using which SDKs (if any). Calls to an API endpoint are undifferentiated by the context in which they happen. But that additional information is indispensable when it comes to customer support and planning future product development.
In this tutorial, we will walkthrough how to use the Speakeasy platform to generate telemetry on your API’s SDK usage by customer.
Setting up Speakeasy Request Tracking
The first step in understanding language preferences is capturing the data flowing through your API and making it surfacable. You could build and host an entire custom logging infrastructure for this, but we recommend using Speakeasy. Setting up is just a couple of steps:
- Add our SDK to your API definition. Speakeasy will autocapture a whole bunch of data (endpoint, status, headers, response object, etc.) from your API’s request/response data by default, but there’s one super important field you’ll need to add to your API’s methods.
- Track the customer id in your API request data by configuring it as a captured field in the Speakeasy middleware. This will enable you to sort and aggregate the data in the platform to draw out customer insights.
Populating The Language Attribute
The next step to understanding language usage is to make sure the SDKs your customers use pass the language information in the API request. Specifying the language in the API request data for the Speakeasy platform to make sense of.
By default Speakeasy expects that the user-agent header will be used to store this data. If your APIs are already using the user-agent header for another purpose, then you can set a x-speakeasy-user-agent header instead.
The Speakeasy platform will expect the value of this header to follow the format:
speakeasy-sdk/language vSDKversion.x.x vCLIversion.x.x
For example, v3 of your Go SDK would be:
speakeasy-sdk/go v3.0.0 v0.0.0
Because we are not using the Speakeasy CLI, we will set the CLI version to v0.0.0
To populate this header in your API request data, you’ll need to add a line to each of the SDKs you want to add telemetry to. Here is an example of adding the header to a method in a Go SDK:
func (s *Pets) CreatePets(ctx context.Context) (*operations.CreatePetsResponse, error) {
baseURL := s._serverURL
url := strings.TrimSuffix(baseURL, "/") + "/pets"
req, err := http.NewRequestWithContext(ctx, "POST", url, nil)
if err != nil {
return nil, fmt.Errorf("error creating request: %w", err)
}
req.Header.Set("user-agent", fmt.Sprintf("speakeasy-sdk/%s %s %s", s._language, s._sdkVersion, s._genVersion))
...
}
If you want telemetry without needing to think about it, Speakeasy can manage SDKs as a fully automated workflow. For more information, see how you can get started generating SDKs from your OpenAPI spec with telemetry baked-in.
At this point, you’re ready to start diving into the usage charts and understanding client SDK usage.
Understanding Language Usage
Head into the Speakeasy dashboard and over to the usage tab, you will now be able to use the SDK filter to breakdown your API’s traffic by SDK language.
Understanding language preference across your entire user base is useful, but often you want to know the preferences of a specific customer. To retrieve that information, simply filter for the customer in question, and you’ll be able to see their usage across language.
Using insights to improve your business
The uses for SDK usage telemetry is only limited by your imagination, but here are a few common use cases that can help you improve decision making around developing, selling, and supporting your APIs:
- Product development: Telemetry data can help the company understand which languages are most popular among developers using your API. This can inform product development decisions, such as which languages to prioritize when adding new features or fixing bugs.
- GTM Strategy: Telemetry data can be used to inform marketing efforts. For example, if the company sees that a particular language is gaining popularity among developers, they may decide to target their marketing efforts at developers using that language.
- Customer Support: Customer support teams better understand the needs and preferences of individual customers. They can make sure that all communication with the client is in the language the client is familiar with.