Skip to main content

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 visualize DynamicTracing signposts.
  • Category.DynamicStackTracing: this category behaves like DynamicTracing, 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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

os-signpost-0.0.3.tar.gz (5.3 kB view details)

Uploaded Source

Built Distributions

os_signpost-0.0.3-cp310-cp310-macosx_11_0_arm64.whl (33.9 kB view details)

Uploaded CPython 3.10 macOS 11.0+ ARM64

os_signpost-0.0.3-cp310-cp310-macosx_10_9_x86_64.whl (35.0 kB view details)

Uploaded CPython 3.10 macOS 10.9+ x86-64

os_signpost-0.0.3-cp39-cp39-macosx_11_0_arm64.whl (33.6 kB view details)

Uploaded CPython 3.9 macOS 11.0+ ARM64

os_signpost-0.0.3-cp39-cp39-macosx_10_9_x86_64.whl (34.7 kB view details)

Uploaded CPython 3.9 macOS 10.9+ x86-64

os_signpost-0.0.3-cp38-cp38-macosx_11_0_arm64.whl (33.6 kB view details)

Uploaded CPython 3.8 macOS 11.0+ ARM64

os_signpost-0.0.3-cp38-cp38-macosx_10_9_x86_64.whl (34.4 kB view details)

Uploaded CPython 3.8 macOS 10.9+ x86-64

os_signpost-0.0.3-cp37-cp37m-macosx_10_9_x86_64.whl (34.1 kB view details)

Uploaded CPython 3.7m macOS 10.9+ x86-64

File details

Details for the file os-signpost-0.0.3.tar.gz.

File metadata

  • Download URL: os-signpost-0.0.3.tar.gz
  • Upload date:
  • Size: 5.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.7.9

File hashes

Hashes for os-signpost-0.0.3.tar.gz
Algorithm Hash digest
SHA256 344b07683a4d5d8eb7db569db39a4eb54d21f8dd44876624f88f60f9d77cf1b1
MD5 11a0fb1494180c7510703fd03b91bc49
BLAKE2b-256 76ab0b9e4eca5b3ad1207d387625dfc7e4bd4aeef06498efe9966f0fca5550f1

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for os_signpost-0.0.3-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c0dd7eb7de2aa5cfe9d2c3eae05c3b265a6a21c51e2e5d0a9c151eca3605d7c4
MD5 a264d69cb92de1212f584263abd8e2ed
BLAKE2b-256 e2a61d227aa34e7d0759b004dc9d72fadee5f9d25ba3ca731f59b09a9df15357

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp310-cp310-macosx_10_9_x86_64.whl.

File metadata

File hashes

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

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp39-cp39-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for os_signpost-0.0.3-cp39-cp39-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1750471bb8588b22b00936d95000d9533596359988c8eb9643cd35a6df92c25c
MD5 ba969c6a1ca35be772e5b3f1642faf74
BLAKE2b-256 98161a0ed9a4d47ac94f3a6906500684618449041a278b9ef664439bc2380acd

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp39-cp39-macosx_10_9_x86_64.whl.

File metadata

File hashes

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

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp38-cp38-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for os_signpost-0.0.3-cp38-cp38-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0db652de691066a56b6a8043431a08b485ea165e7eb8b1e490b4adf6c9502ad0
MD5 2002205192141d2a58d35861d8151ca6
BLAKE2b-256 7c487f52e6d06895edeb5556de05b509642b4f48b452e112673ec9dbcbac768e

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp38-cp38-macosx_10_9_x86_64.whl.

File metadata

File hashes

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

See more details on using hashes here.

File details

Details for the file os_signpost-0.0.3-cp37-cp37m-macosx_10_9_x86_64.whl.

File metadata

File hashes

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

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page