Skip to main content


Previous Version

Still using the Python (Legacy) runtime? Docs for the previous version are available here.

Iteratively supports tracking analytics events from Python 3 applications.


Generate the SDK

If you have not yet installed the Ampli CLI, install it now.

To generate the Itly SDK, run ampli pull {source} in the top-most folder of your project. By default, the SDK will be generated in ./itly/.


{source} is the name of the source you created in your tracking plan (e.g. python).

Install dependencies

The generated Itly SDK will automatically reference its dependencies based on the destinations you've configured in your tracking plan. By default, the SDK depends on itly-sdk (the base Itly library) and the itly-plugin-schema-validator (the event validation plugin). Optionally, it also depends on provider-specific plugins like itly-plugin-amplitude.

To install these dependencies into your project:

  • Add -r itly/requirements.txt to your requirements.txt
  • Run pip as usual

You can also run pip install -r itly/requirements.txt to install the dependencies yourself.

Import into your app

First, import the Itly package in files you'll be interacting with the Itly SDK:

import itly



Then, initialize the Itly SDK once your application starts up. For example:


To initialize the Itly SDK, call its load() function. In our example above, we defined a tracking plan in the Itly web application to:

  • Include a property called version on every event
  • Send events to a custom destination

As a result, our SDK will be initialized to:

  • Set the required version property to 1.0
  • Send events to a custom destination implemented in the CustomDestination class

Note: if your tracking plan doesn't take advantage of source templates and you haven't configured a custom destination, you can simply call itly.load().

contextAn object with a set of properties to add to every event sent by the Itly SDK.

Only available if there is at least one source template associated with your your team's tracking plan.
destinationsSpecifies any analytics provider-specific configuration. The Itly SDK passes these objects in when loading the underlying analytics provider libraries.

optionsSpecifies additional configuration options for the Itly SDK. Optional.

Specifies whether the Itly SDK does any work. When true, all calls to the Itly SDK will be no-ops. Useful in local or development environments.

Optional. Defaults to false.

Specifies the environment the Itly SDK is running in: either itly.Environment.PRODUCTION or itly.Environment.DEVELOPMENT. Environment determines which Access Token is used to load the underlying analytics provider libraries.

The option also determines safe defaults for handling event validation errors. In production, when the SDK detects an invalid event, it will log an error but still let the event through. In development, the SDK will throw an exception to alert you that something is wrong.

Optional. Defaults to itly.Environment.DEVELOPMENT.

An array of additional plugins to load into the Itly SDK. Plugins allow you to extend the Itly SDK's event validation and event tracking functionality with your own. For example, a plugin can be used to implement a custom destination or a custom event validator.

Click here to see a sample custom destination plugin.


To log Itly's logs to a custom logger, implement the ItlyLogger protocol and set logger to an instance of your class. The Itly SDK will call into your class with all debug, info, warn, and error-level messages.

Click here to see a a sample custom logger.



And finally, to track an event:


Every event defined in your team's Itly tracking plan turns into a function in the Itly SDK. To track the event, call the function, provide a unique ID to track the user by, and specify the event's properties, if any.

For example, in the code snippet above, our tracking plan contains an event called Process Started. The event was defined with one required property called availableProcessors. The property's type is an integer.

Note: if your Python application or service isn't intended to run forever, you'll need to shut down the Itly SDK when your application or service shuts down. To do this, call itly.flush() followed by itly.shutdown().


Browse over to to see an example of an instrumented Python app, along with a sample implementation of the CustomDestination adapter and SampleLogger logger.