{"id":21228343,"url":"https://github.com/lttng/lttng-ust","last_synced_at":"2025-10-26T10:16:17.755Z","repository":{"id":16170244,"uuid":"18916501","full_name":"lttng/lttng-ust","owner":"lttng","description":"This repo is a mirror of the official lttng-ust git found at git://git.lttng.org/lttng-ust.git. LTTng-UST, the Linux Trace Toolkit Next Generation Userspace Tracer, is port of the low-overhead tracing capabilities of the LTTng kernel tracer to user-space. The library \"liblttng-ust\" enables tracing of applications and libraries.","archived":false,"fork":false,"pushed_at":"2025-05-14T19:38:02.000Z","size":6961,"stargazers_count":132,"open_issues_count":0,"forks_count":71,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-14T20:43:26.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://lttng.org/","language":"C","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lttng.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2014-04-18T15:13:06.000Z","updated_at":"2025-04-24T17:07:00.000Z","dependencies_parsed_at":"2023-01-14T12:45:26.851Z","dependency_job_id":"6ceb3d07-e6de-4a9f-bb95-5ef812285acd","html_url":"https://github.com/lttng/lttng-ust","commit_stats":{"total_commits":3054,"total_committers":78,"mean_commits":39.15384615384615,"dds":0.5134250163719711,"last_synced_commit":"7d54bba42d167e5d74dfdff858153742b199b4f6"},"previous_names":[],"tags_count":144,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lttng%2Flttng-ust","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lttng%2Flttng-ust/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lttng%2Flttng-ust/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lttng%2Flttng-ust/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lttng","download_url":"https://codeload.github.com/lttng/lttng-ust/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"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-11-20T23:18:01.584Z","updated_at":"2025-10-26T10:16:17.725Z","avatar_url":"https://github.com/lttng.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!--\nSPDX-FileCopyrightText: 2023 EfficiOS, Inc.\n\nSPDX-License-Identifier: CC-BY-4.0\n--\u003e\n\nLTTng-UST\n=========\n\nThe LTTng User Space Tracing (LTTng-UST) library allows any C/C++\napplication to be instrumented for and traced by\n[LTTng](http://lttng.org/). LTTng-UST also includes a logging\nback-end for Java applications and various dynamically loadable\nuser space tracing helpers for any application.\n\n\nPrerequisites\n-------------\n\nLTTng-UST depends on **[liburcu](http://liburcu.org/) \u003e= 0.15** at build\ntime. It also optionally depends on libnuma.\n\n\nBuilding\n--------\n\n### Prerequisites\n\nThis source tree is based on the Autotools suite from GNU to simplify\nportability. Here are some things you should have on your system in order to\ncompile the Git repository tree:\n\n  - [GNU Autotools](http://www.gnu.org/software/autoconf/)\n    (**Automake \u003e= 1.12**, **Autoconf \u003e= 2.69**,\n    **Autoheader \u003e= 2.69**;\n    make sure your system-wide `automake` points to a recent version!)\n  - **[GNU Libtool](https://www.gnu.org/software/libtool/) \u003e= 2.2**\n  - **[GNU Make](https://www.gnu.org/software/make/)**\n  - **[pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)**\n\n\n### Optional dependencies\n\nOptional packages to build LTTng-ust man pages:\n\n  - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) \u003e= 8.4.5**\n    (previous versions may work, but were not tested)\n  - **[xmlto](https://fedorahosted.org/xmlto/) \u003e= 0.0.21** (previous\n    versions may work, but were not tested)\n\nNote that the man pages are already built in a distribution tarball.\nIn this case, you only need AsciiDoc and xmlto if you indend to modify\nthe AsciiDoc man page sources.\n\nNeeded for `make check` and tests:\n\n  - **[Perl](https://www.perl.org/)**\n\n\n### Building steps\n\nIf you get the tree from the Git repository, you will need to run\n\n    ./bootstrap\n\nin its root. It calls all the GNU tools needed to prepare the tree\nconfiguration.\n\nTo build LTTng-UST, do:\n\n    ./configure\n    make\n    sudo make install\n    sudo ldconfig\n\n**Note:** the `configure` script sets `/usr/local` as the default prefix for\nfiles it installs. However, this path is not part of most distributions'\ndefault library path, which will cause builds depending on `liblttng-ust`\nto fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a\ncustom prefix to `configure` by using the `--prefix` switch\n(e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_\nthe tracepoint probe provider is statically linked into the application.\n\n\nUsing\n-----\n\nFirst of all, create an instrumentation header following the\n[tracepoint examples](doc/examples).\n\nThere are two ways to compile the tracepoint provider and link it with\nyour application: statically or dynamically. Please follow carefully one\nor the other method.\n\n\n### Static linking\n\nThis method links the tracepoint provider with the application,\neither directly or through a static library (`.a`):\n\n  1. Into exactly one unit (C/C++ source file) of your _application_,\n     define `LTTNG_UST_TRACEPOINT_DEFINE` and include the tracepoint provider\n     header.\n  2. Include the tracepoint provider header into all C/C++ files using\n     the provider and insert tracepoints using the `tracepoint()` macro.\n  3. Use `-I.` when compiling the unit defining `LTTNG_UST_TRACEPOINT_DEFINE`\n     (e.g., `tp.c`).\n  4. Link the application with `-ldl` on Linux, or with `-lc` on BSD,\n     and with `-llttng-ust`.\n\nExample:\n\n    gcc -c -I. tp.c\n    gcc -c some-source.c\n    gcc -c other-source.c\n    gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust\n\nRun the application directly:\n\n    ./my-app\n\nOther relevant examples:\n\n  - [`doc/examples/easy-ust`](doc/examples/easy-ust)\n  - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib)\n\n\n### Dynamic loading\n\nThis method decouples the tracepoint provider from the application,\nmaking it dynamically loadable.\n\n  1. Into exactly one unit of your _application_, define\n     `LTTNG_UST_TRACEPOINT_DEFINE` _and_ `LTTNG_UST_TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,\n     then include the tracepoint provider header.\n  2. Include the tracepoint provider header into all C/C++ files using\n     the provider and insert tracepoints using the `tracepoint()` macro.\n  3. Use `-I.` and `-fpic` when compiling the tracepoint provider\n     (e.g., `tp.c`).\n  4. Link the tracepoint provider with `-llttng-ust` and make it a\n     shared object with `-shared`.\n  5. Link the application with `-ldl` on Linux, or with `-lc` on BSD.\n\nExample:\n\n    gcc -c -I. -fpic tp.c\n    gcc -o tp.so -shared tp.o -llttng-ust\n    gcc -o my-app some-source.c other-source.c -ldl\n\nTo run _without_ LTTng-UST support:\n\n    ./my-app\n\nTo run with LTTng-UST support (register your tracepoint provider,\n`tp.so`):\n\n    LD_PRELOAD=./tp.so ./my-app\n\nYou could also use `libdl` directly in your application and `dlopen()`\nyour tracepoint provider shared object (`tp.so`) to make LTTng-UST\ntracing possible.\n\nOther relevant examples:\n\n  - [`doc/examples/demo`](doc/examples/demo)\n\n\n### Controlling tracing and viewing traces\n\nUse [LTTng-tools](https://lttng.org/download) to control the tracer.\nUse [Babeltrace](https://lttng.org/babeltrace) to print traces as a\nhuman-readable text log.\n\n\n### Environment variables and compile flags\n\n  - `liblttng-ust` debug can be activated by setting the environment\n    variable `LTTNG_UST_DEBUG` when launching the user application. It\n    can also be enabled at build time by compiling LTTng-UST with\n    `-DLTTNG_UST_DEBUG`.\n  - `liblttng-ust` abort on critical can be activated by setting the\n    environment variable `LTTNG_UST_ABORT_ON_CRITICAL` when launching the user\n    application. It can also be enabled at build time by compiling LTTng-UST with\n    `-DLTTNG_UST_ABORT_ON_CRITICAL`.\n  - The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to\n    specify how long the applications should wait for the session\n    daemon  _registration done_ command before proceeding to execute the\n    main program. The default is 3000 ms (3 seconds). The timeout value\n    is specified in milliseconds. The value 0 means _don't wait_. The\n    value -1 means _wait forever_. Setting this environment variable to 0\n    is recommended for applications with time constraints on the process\n    startup time.\n  - The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled\n    at build time to allow `liblttng-ust` to be used with Valgrind\n    (side-effect: disables per-CPU buffering).\n\n\n### Notes\n\n#### C++ support\n\nSince LTTng-UST 2.3, both tracepoints and tracepoint providers can be\ncompiled in C++. To compile tracepoint probes in C++, you need\nG++ \u003e= 4.7 or Clang \u003e= 4.0. The C++ compilers need to support C++11.\n\n\nSupported versions\n------------------\n\nThe LTTng project supports the last two released stable versions\n(e.g. stable-2.13 and stable-2.12).\n\nFixes are backported from the master branch to the last stable version\nunless those fixes would break the ABI or API. Those fixes may be backported\nto the second-last stable version, depending on complexity and ABI/API\ncompatibility.\n\nSecurity fixes are backported from the master branch to both of the last stable\nversion and the the second-last stable version.\n\nNew features are integrated into the master branch and not backported to the\nlast stable branch.\n\nContact\n-------\n\nMaintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)\n\nMailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)\n\nCode review: [_lttng-ust_ project](https://review.lttng.org/q/project:lttng-ust) on LTTng Review\n\nPackage contents\n----------------\n\nThis package contains the following elements:\n\n  - `doc`: LTTng-UST documentation and examples.\n  - `include`: the public header files that will be installed on the\n    system.\n  - `liblttng-ust`: the actual userspace tracing library that must be\n    linked to the instrumented programs.\n  - `liblttng-ust-comm`: a static library shared between `liblttng-ust`\n    and LTTng-tools, that provides functions that allow these components\n    to communicate together.\n  - `liblttng-ust-ctl`: a library to control tracing in other processes;\n     used by LTTng-tools.\n  - `liblttng-ust-cyg-profile`: a library that can be preloaded (using\n    `LD_PRELOAD`) to instrument function entries and exits when the target\n    application is built with the GCC flag `-finstrument-functions`.\n  - `liblttng-ust-dl`: a library that can be preloaded to instrument\n    calls to `dlopen()` and `dlclose()`.\n  - `liblttng-ust-fork`: a library that is preloaded and that hijacks\n    calls to several system calls in order to trace across these calls.\n    It _has_ to be preloaded in order to hijack calls. In contrast,\n    `liblttng-ust` may be linked at build time.\n  - `liblttng-ust-java`: a simple library that uses JNI to allow tracing\n    in Java programs. (Configure with `--enable-jni-interface`).\n  - `liblttng-ust-java-agent`: a package that includes a JNI library and a\n    JAR library to provide an LTTng-UST logging back-end for Java\n    applications using Java Util Logging or Log4j. (Configure with\n    `--enable-java-agent-jul` or `--enable-java-agent-log4j` or\n    `--enable-java-agent-log4j2` or `--enable-java-agent-all`).\n  - `liblttng-ust-libc-wrapper`: an example library that can be\n    preloaded to instrument some calls to libc (currently `malloc()` and\n    `free()`) and to POSIX threads (mutexes currently instrumented) in\n    any program without need to recompile it.\n  - `liblttng-ust-python-agent`: a library used by python-lttngust to allow\n    tracing in Python applications. (Configure with `--enable-python-agent`)\n  - `libringbuffer`: the ring buffer implementation used within LTTng-UST.\n  - `python-lttngust`: a package to provide an LTTng-UST logging back-end\n    for Python applications using the standard logging framework.\n  - `snprintf`: an asynchronous signal-safe version of `snprintf()`.\n  - `tests`: various test programs.\n  - `tools`: home of `lttng-gen-tp`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flttng%2Flttng-ust","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flttng%2Flttng-ust","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flttng%2Flttng-ust/lists"}