{"id":10310,"url":"https://patchwork.libcamera.org/api/patches/10310/?format=json","web_url":"https://patchwork.libcamera.org/patch/10310/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20201030085756.79329-6-paul.elder@ideasonboard.com>","date":"2020-10-30T08:57:56","name":"[libcamera-devel,v4,5/5] Documentation: tracing: Add tracing guide","commit_ref":null,"pull_url":null,"state":"accepted","archived":false,"hash":"d7c2685202b7bda1cac54a25784c7ed2e3e043f2","submitter":{"id":17,"url":"https://patchwork.libcamera.org/api/people/17/?format=json","name":"Paul Elder","email":"paul.elder@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/10310/mbox/","series":[{"id":1435,"url":"https://patchwork.libcamera.org/api/series/1435/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=1435","date":"2020-10-30T08:57:51","name":"Tracing","version":4,"mbox":"https://patchwork.libcamera.org/series/1435/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/10310/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/10310/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 26C09BDB1E\n\tfor ;\n\tFri, 30 Oct 2020 08:58:17 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id E886162979;\n\tFri, 30 Oct 2020 09:58:16 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 084CF628A5\n\tfor ;\n\tFri, 30 Oct 2020 09:58:15 +0100 (CET)","from pyrite.rasen.tech (unknown\n\t[IPv6:2400:4051:61:600:2c71:1b79:d06d:5032])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 3C68F9B7;\n\tFri, 30 Oct 2020 09:58:12 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com;\n\tdkim=fail reason=\"signature verification failed\" (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"RJX1PfR0\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1604048294;\n\tbh=2kOoaciY+HnAFQ6qs4Pfm49M1NlG3j95wVFQF3CtmhQ=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=RJX1PfR0uE9bw0dPIhzvmXeGrov/ym2dRlhZy9Bdxf6/+1pG6kb9HKQmau1RK8ATt\n\tmKN2bJZZnv/Td2/VtnlXmxXuRqqn9I596l6+2HS24S8w0QyEOB2IaS0QvHCwNpKQ04\n\tEADI+5pu0Y2np+YbUOChdEOlD6JYkPB6zO10i2DA=","From":"Paul Elder ","To":"libcamera-devel@lists.libcamera.org","Date":"Fri, 30 Oct 2020 17:57:56 +0900","Message-Id":"<20201030085756.79329-6-paul.elder@ideasonboard.com>","X-Mailer":"git-send-email 2.27.0","In-Reply-To":"<20201030085756.79329-1-paul.elder@ideasonboard.com>","References":"<20201030085756.79329-1-paul.elder@ideasonboard.com>","MIME-Version":"1.0","Subject":"[libcamera-devel] [PATCH v4 5/5] Documentation: tracing: Add\n\ttracing guide","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","Content-Type":"text/plain; charset=\"us-ascii\"","Content-Transfer-Encoding":"7bit","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"Add guide for tracepoints, including how to define and use them.\n\nSigned-off-by: Paul Elder \nReviewed-by: Laurent Pinchart \n\n---\nChanges in v4:\n- fix spelling and some indentation\n- rebase on master instead of ipc\n\nChanges in v3:\n- fix compilation error\n- reword english\n- add stuff about the new IPA call tracepoint macros\n\nNew in v2\n---\n Documentation/guides/tracing.rst | 141 +++++++++++++++++++++++++++++++\n Documentation/index.rst | 1 +\n Documentation/meson.build | 1 +\n 3 files changed, 143 insertions(+)\n create mode 100644 Documentation/guides/tracing.rst","diff":"diff --git a/Documentation/guides/tracing.rst b/Documentation/guides/tracing.rst\nnew file mode 100644\nindex 00000000..9c688b93\n--- /dev/null\n+++ b/Documentation/guides/tracing.rst\n@@ -0,0 +1,141 @@\n+.. SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+Tracing Guide\n+=============\n+\n+Guide to tracing in libcamera.\n+\n+Profiling vs Tracing\n+--------------------\n+\n+Tracing is recording timestamps at specific locations. libcamera provides a\n+tracing facility. This guide shows how to use this tracing facility.\n+\n+Tracing should not be confused with profiling, which samples execution\n+at periodic points in time. This can be done with other tools such as\n+callgrind, perf, gprof, etc., without modification to the application,\n+and is out of scope for this guide.\n+\n+Compiling\n+---------\n+\n+To compile libcamera with tracing support, it must be enabled through the\n+meson ``tracing`` option. It depends on the lttng-ust library (available in the\n+``liblttng-ust-dev`` package for Debian-based distributions).\n+By default the tracing option in meson is set to ``auto``, so if\n+liblttng is detected, it will be enabled by default. Conversely, if the option\n+is set to disabled, then libcamera will be compiled without tracing support.\n+\n+Defining tracepoints\n+--------------------\n+\n+libcamera already contains a set of tracepoints. To define additional\n+tracepoints, create a file\n+``include/libcamera/internal/tracepoints/{file}.tp``, where ``file`` is a\n+reasonable name related to the category of tracepoints that you wish to\n+define. For example, the tracepoints file for the Request object is called\n+``request.tp``. An entry for this file must be added in\n+``include/libcamera/internal/tracepoints/meson.build``.\n+\n+In this tracepoints file, define your tracepoints `as mandated by lttng\n+`_. The header boilerplate must *not* be\n+included (as it will conflict with the rest of our infrastructure), and\n+only the tracepoint definitions (with the ``TRACEPOINT_*`` macros) should be\n+included.\n+\n+All tracepoint providers shall be ``libcamera``. According to lttng, the\n+tracepoint provider should be per-project; this is the rationale for this\n+decision. To group tracepoint events, we recommend using\n+``{class_name}_{tracepoint_name}``, for example, ``request_construct`` for a\n+tracepoint for the constructor of the Request class.\n+\n+Tracepoint arguments may take C++ objects pointers, in which case the usual\n+C++ namespacing rules apply. The header that contains the necessary class\n+definitions must be included at the top of the tracepoint provider file.\n+\n+Note: the final parameter in ``TP_ARGS`` *must not* have a trailing comma, and\n+the parameters to ``TP_FIELDS`` are *space-separated*. Not following these will\n+cause compilation errors.\n+\n+Using tracepoints (in libcamera)\n+--------------------------------\n+\n+To use tracepoints in libcamera, first the header needs to be included:\n+\n+``#include \"libcamera/internal/tracepoints.h\"``\n+\n+Then to use the tracepoint:\n+\n+``LIBCAMERA_TRACEPOINT({tracepoint_event}, args...)``\n+\n+This macro must be used, as opposed to lttng's macros directly, because\n+lttng is an optional dependency of libcamera, so the code must compile and run\n+even when lttng is not present or when tracing is disabled.\n+\n+The tracepoint provider name, as declared in the tracepoint definition, is not\n+included in the parameters of the tracepoint.\n+\n+There are also two special tracepoints available for tracing IPA calls:\n+\n+``LIBCAMERA_TRACEPOINT_IPA_BEGIN({pipeline_name}, {ipa_function})``\n+\n+``LIBCAMERA_TRACEPOINT_IPA_END({pipeline_name}, {ipa_function})``\n+\n+These shall be placed where an IPA function is called from the pipeline handler,\n+and when the pipeline handler receives the corresponding response from the IPA,\n+respectively. These are the tracepoints that our sample analysis script\n+(see \"Analyzing a trace\") scans for when computing statistics on IPA call time.\n+\n+Using tracepoints (from an application)\n+---------------------------------------\n+\n+As applications are not part of libcamera, but rather users of libcamera,\n+applications should seek their own tracing mechanisms. For ease of tracing\n+the application alongside tracing libcamera, it is recommended to also\n+`use lttng `_.\n+\n+Using tracepoints (from closed-source IPA)\n+------------------------------------------\n+\n+Similar to applications, closed-source IPAs can simply use lttng on their own,\n+or any other tracing mechanism if desired.\n+\n+Collecting a trace\n+------------------\n+\n+A trace can be collected fairly simply from lttng:\n+\n+.. code-block:: bash\n+\n+ lttng create $SESSION_NAME\n+ lttng enable-event -u libcamera:\\*\n+ lttng start\n+ # run libcamera application\n+ lttng stop\n+ lttng view\n+ lttng destroy $SESSION_NAME\n+\n+See the `lttng documentation `_ for further details.\n+\n+Analyzing a trace\n+-----------------\n+\n+As mentioned above, while an lttng tracing session exists and the trace is not\n+running, the trace output can be viewed as text by ``lttng view``.\n+\n+The trace log can also be viewed as text using babeltrace2. See the\n+`lttng trace analysis documentation\n+`_\n+for further details.\n+\n+babeltrace2 also has a C API and python bindings that can be used to process\n+traces. See the\n+`lttng python bindings documentation `_\n+and the\n+`lttng C API documentation `_\n+for more details.\n+\n+As an example, there is a script ``utils/tracepoints/analyze-ipa-trace.py``\n+that gathers statistics for the time taken for an IPA function call, by\n+measuring the time difference between pairs of events\n+``libcamera:ipa_call_start`` and ``libcamera:ipa_call_finish``.\ndiff --git a/Documentation/index.rst b/Documentation/index.rst\nindex a30688ac..ff697d4f 100644\n--- a/Documentation/index.rst\n+++ b/Documentation/index.rst\n@@ -16,3 +16,4 @@\n Developer Guide \n Application Writer's Guide \n Pipeline Handler Writer's Guide \n+ Tracing guide \ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex d3d64f71..26a12fcd 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -56,6 +56,7 @@ if sphinx.found()\n 'guides/introduction.rst',\n 'guides/application-developer.rst',\n 'guides/pipeline-handler.rst',\n+ 'guides/tracing.rst',\n ]\n \n release = 'release=v' + libcamera_git_version\n","prefixes":["libcamera-devel","v4","5/5"]}