{"id":15014051,"url":"https://github.com/explosion/os-signpost","last_synced_at":"2025-10-19T14:31:54.010Z","repository":{"id":41290456,"uuid":"508667416","full_name":"explosion/os-signpost","owner":"explosion","description":"Wrapper for the macOS signpost API","archived":false,"fork":false,"pushed_at":"2023-04-24T07:23:43.000Z","size":437,"stargazers_count":13,"open_issues_count":0,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-01-29T18:38:17.372Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Cython","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/explosion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-29T11:41:56.000Z","updated_at":"2024-10-05T18:48:07.000Z","dependencies_parsed_at":"2024-09-16T01:17:02.108Z","dependency_job_id":null,"html_url":"https://github.com/explosion/os-signpost","commit_stats":{"total_commits":17,"total_committers":2,"mean_commits":8.5,"dds":0.05882352941176472,"last_synced_commit":"c6950f9ef9da5734dcc6347e34255773b4e236d4"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fos-signpost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fos-signpost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fos-signpost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/explosion%2Fos-signpost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/explosion","download_url":"https://codeload.github.com/explosion/os-signpost/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237152768,"owners_count":19263780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:45:07.383Z","updated_at":"2025-10-19T14:31:53.613Z","avatar_url":"https://github.com/explosion.png","language":"Cython","readme":"# os-signpost\n\nmacOS provides the\n[`OSSignposter`](https://developer.apple.com/documentation/os/ossignposter) API\nfor measuring the duration of tasks in a program or marking events. These\nso-called signposts can be visualized in the\n[Instruments.app](\u003chttps://en.wikipedia.org/wiki/Instruments_(software)\u003e) application.\nThis Python package provides a wrapper for the `OSSignposter` API, so that you\ncan mark tasks and events in Python applications.\n\n![](images/signposts.png)\n\n## ⏳ Install\n\nMake sure you have [Xcode](https://developer.apple.com/xcode/) installed and\nthen install with `pip`:\n\n```bash\npip install os-signpost\n```\n\n## 🚀 Quickstart\n\n### Creating a `Signposter`\n\n`Signposter` is the main class of this package. You should create an instance of\n`Signposter` in order to emit an event. You can create an instance as follows:\n\n```python\nfrom os_signpost import Signposter\nsignposter = Signposter(\"com.example.my_subsystem\", Signposter.Category.DynamicTracing)\n```\n\nThe first argument to the constructor is the name of the subsystem, which is\nusually the name of your organization followed by the name of the subsystem.\nThe second argument is the category within the subsystem. The system uses the\ncategory to filter events. There are three predefined categories available:\n\n- `Category.PointsOfInterest`: signposts with this category are always enabled.\n  The _Points of Interest_ instrument shows signposts with this category.\n- `Category.DynamicTracing`: signposts with this category are only enabled when\n  recording with a performance tool like Instruments.app. Create an os_signpost\n  instrument that filters for the subsystem name to visualize `DynamicTracing`\n  signposts.\n- `Category.DynamicStackTracing`: this category behaves like `DynamicTracing`,\n  but also records backtraces.\n\n### Make signposts for the duration of a tasks\n\nTo measure the duration of a task, you can create signposts that mark an\ninterval. The `Signposter.begin_interval` method adds a signpost that marks the\nbeginning of an interval and returns a callback. This callback then marks the\nend of the interval:\n\n```python\nend_interval = signposter.begin_interval(\"begin my task\")\n# The task for which you want to measure the duration.\nend_interval(\"end my task\")\n```\n\nBoth the `begin_interval` method and the callback take a message.\nInstruments.app includes these messages in the visualization and allows you to\ncategorize intervals by their messages. When no message is specified for the\ninterval end, the same message as the begin will be used.\n\nYou can also use the `Signposter.use_interval` context manager in place of the\ncallback approach:\n\n```python\nwith signposter.use_interval(\"begin my task\", \"end my task\"):\n    # The task for which you want to measure the duration.\n```\n\n`use_interval` takes the begin and end messages as its arguments. The end\nmessage is also optional for the context manager.\n\n### Emitting an event\n\nBesides marking intervals, you can also emit an event signpost. Instruments.app\nshows events as single points. The `Signposter.emit_event` method emits an\nevent:\n\n```python\nsignposter.emit_event(\"lp0 on fire\")\n```\n\n## 🙈 Limitations\n\nThe macOS signpost API also allows associating a name with a signpost. However,\nthis name is required to be a C string literal. Therefore, we hardcode the name\nof signposts `python`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexplosion%2Fos-signpost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexplosion%2Fos-signpost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexplosion%2Fos-signpost/lists"}