macOS signpost API wrapper
Project description
os-signpost
macOS provides the
OSSignposter
API
for measuring the duration of tasks in a program or marking events. These
so-called signposts can be visualized in the
Instruments.app application.
This Python package provides a wrapper for the OSSignposter
API, so that you
can mark tasks and events in Python applications.
⏳ Install
Make sure you have Xcode installed and
then install with pip
:
pip install os-signpost
🚀 Quickstart
Creating a Signposter
Signposter
is the main class of this package. You should create an instance of
Signposter
in order to emit an event. You can create an instance as follows:
from os_signpost import Signposter
signposter = Signposter("com.example.my_subsystem", Signposter.Category.DynamicTracing)
The first argument to the constructor is the name of the subsystem, which is usually the name of your organization followed by the name of the subsystem. The second argument is the category within the subsystem. The system uses the category to filter events. There are three predefined categories available:
Category.PointsOfInterest
: signposts with this category are always enabled. The Points of Interest instrument shows signposts with this category.Category.DynamicTracing
: signposts with this category are only enabled when recording with a performance tool like Instruments.app. Create an os_signpost instrument that filters for the subsystem name to visualizeDynamicTracing
signposts.Category.DynamicStackTracing
: this category behaves likeDynamicTracing
, but also records backtraces.
Make signposts for the duration of a tasks
To measure the duration of a task, you can create signposts that mark an
interval. The Signposter.begin_interval
method adds a signpost that marks the
beginning of an interval and returns a callback. This callback then marks the
end of the interval:
end_interval = signposter.begin_interval("begin my task")
# The task for which you want to measure the duration.
end_interval("end my task")
Both the begin_interval
method and the callback take a message.
Instruments.app includes these messages in the visualization and allows you to
categorize intervals by their messages. When no message is specified for the
interval end, the same message as the begin will be used.
You can also use the Signposter.use_interval
context manager in place of the
callback approach:
with signposter.use_interval("begin my task", "end my task"):
# The task for which you want to measure the duration.
use_interval
takes the begin and end messages as its arguments. The end
message is also optional for the context manager.
Emitting an event
Besides marking intervals, you can also emit an event signpost. Instruments.app
shows events as single points. The Signposter.emit_event
method emits an
event:
signposter.emit_event("lp0 on fire")
🙈 Limitations
The macOS signpost API also allows associating a name with a signpost. However,
this name is required to be a C string literal. Therefore, we hardcode the name
of signposts python
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for os_signpost-0.0.3-cp310-cp310-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c0dd7eb7de2aa5cfe9d2c3eae05c3b265a6a21c51e2e5d0a9c151eca3605d7c4 |
|
MD5 | a264d69cb92de1212f584263abd8e2ed |
|
BLAKE2b-256 | e2a61d227aa34e7d0759b004dc9d72fadee5f9d25ba3ca731f59b09a9df15357 |
Hashes for os_signpost-0.0.3-cp310-cp310-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d6f36ab8f7a21d42b65b06362bfc2f48e66e4a66b8828e0d23d997733c6d8bdc |
|
MD5 | 2f59cbacd613403b8d74c37e801b1378 |
|
BLAKE2b-256 | 0ad4b53c353e5f404dac60b210f9cdebc600f4cd655a71c1744dc1a87d93f600 |
Hashes for os_signpost-0.0.3-cp39-cp39-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1750471bb8588b22b00936d95000d9533596359988c8eb9643cd35a6df92c25c |
|
MD5 | ba969c6a1ca35be772e5b3f1642faf74 |
|
BLAKE2b-256 | 98161a0ed9a4d47ac94f3a6906500684618449041a278b9ef664439bc2380acd |
Hashes for os_signpost-0.0.3-cp39-cp39-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 75c95a7aa717e3de8c4abdb7f3e87e3f596e434979ae9927cb9d5cf04f4ff3e3 |
|
MD5 | 3fb886868ffdd3463fd24506594a801e |
|
BLAKE2b-256 | ce5e251c9b329feacb4b431d1b63f71645d8ba1142a10906b742a759db336f6c |
Hashes for os_signpost-0.0.3-cp38-cp38-macosx_11_0_arm64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0db652de691066a56b6a8043431a08b485ea165e7eb8b1e490b4adf6c9502ad0 |
|
MD5 | 2002205192141d2a58d35861d8151ca6 |
|
BLAKE2b-256 | 7c487f52e6d06895edeb5556de05b509642b4f48b452e112673ec9dbcbac768e |
Hashes for os_signpost-0.0.3-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3d1af4dbcef29efcb8093f456eaeef82e3d20fd5833ed6bbd86ea6753969dfb2 |
|
MD5 | e2dd295cc5dc579fa8a840f92d85cda1 |
|
BLAKE2b-256 | ab5ca24dfa5be4cc68d84cae835358aa6f144d08ee77f2cdb9ca7cdcae7cc491 |
Hashes for os_signpost-0.0.3-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e1aa856fe40a04874c2c7e3948e81a88238fe67a01e106ffdcd9f7757dfa235 |
|
MD5 | 10f9c3b415a9abd111a48d096b442c15 |
|
BLAKE2b-256 | 9fcf21a3c60352587ec8acaddb18e6b8e583b896442fe326feb5c268e973cdbf |