Utilizing User Agent Strings for Telemtry

Overview

Each Speakeasy SDK incorporates a unique user agent string in all HTTP requests made to the API. This string helps identify the source SDK and provides details like the SDK version, the generator version, the document version, and the package name.

Format

The format of the user agent string across all Speakeasy SDKs is as follows:


speakeasy-sdk/<<Language>> {{SDKVersion}} {{GenVersion}} {{DocVersion}} {{PackageName}}

Components:

Language: The language of the SDK (e.g., C#, Java, Python).
SDKVersion: The version of the SDK, specified in gen.yaml.
GenVersion: The version of the Speakeasy generator used.
DocVersion: The version of the OpenAPI document that generated the SDK.
PackageName: The name of the package as defined in gen.yaml.

For a Java SDK, the user agent string might look like this:

speakeasy-sdk/java 2.3.1 1.5.0 2022.01 1.0.0 speakeasyJavaClient

Parsing User Agent Strings

To accurately parse user agent strings, you can use regular expressions, string manipulation techniques, or dedicated parsing libraries.

Below is a Python example using regex and Flask:


from flask import request
import re
@app.route('/some-path')
def some_function():
    user_agent = request.headers.get('User-Agent')
    
    # Regex pattern to match the user agent string
    pattern = r"speakeasy-sdk/(?P<Language>\w+) (?P<SDKVersion>[\d\.]+) (?P<GenVersion>[\d\.]+) (?P<DocVersion>[\d\.]+) (?P<PackageName>[\w\.-]+)"
    # Match the user agent string against the regex pattern
    match = re.match(pattern, user_agent)
    if match:
        details = match.groupdict()
        print(details)

Utilizing Parsed Data for Telemetry

Parsed user agent strings can enhance telemetry in several ways:

Data Enrichment: With parsed user agent strings, you can enhance telemetry records by appending key metadata such as the SDK version, programming language, and package details. This enriched data supports more detailed segmentation and sophisticated analysis, improving the granularity and usability of your telemetry insights. This approach allows you to track feature adoption across different segments and tailor your development focus accordingly.

Monitoring SDK Usage: Utilize the detailed data from user agent strings to monitor the adoption rates of different SDK versions and the prevalence of programming languages among your users. This intelligence is crucial for informed decision-making regarding SDK updates and deprecation schedules. By understanding which versions are most popular and how quickly users adopt new releases, you can better manage support resources and communication strategies.

Performance Analysis: Correlate specific SDK versions or configurations with performance metrics like response times and error rates. This analysis helps pinpoint whether recent updates have improved performance or introduced new issues, allowing your development team to target fixes and optimizations more effectively. Regularly reviewing these correlations helps maintain high performance standards and ensures a positive user experience.

Anomaly Detection: Implement advanced anomaly detection techniques in your telemetry to automatically flag unusual activity, such as a sudden decrease in the usage of a normally popular SDK version or an unexpected increase in error rates following a new release. Early detection of these anomalies can prompt swift action, potentially averting more significant issues and enhancing customer satisfaction. This proactive monitoring is essential in maintaining the reliability and credibility of your SDKs.