From nobody Wed Jun 18 22:16:38 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bMykt74Vwz5y8wD; Wed, 18 Jun 2025 22:16:38 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bMykt6CRtz3Srj; Wed, 18 Jun 2025 22:16:38 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750284998; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=SfH9laT9rv5CsiPPQobeIWYWhtlfzLJUobaE+lgVcrE=; b=qw65RcwTTM5vcYq3cdigCnCjjehvtKppxXP8qvcum6gBiYvjSgKZEQK8Gt5bwSJt4uVMO6 8ELdMoHq6sQjiHvsapjmqTa9HQwF1G2op+bNGVxxUuX/oXpFmmLX77eYLHPcauGfKJiB0y lsqSYJkbooAb/5kRLnBlohdnUwoF0HQuD3nuQn1u9ekq/sLY1xdg5OzCu6+P3DYF7utv1P QyUyccX8OE03pRVeaGXj1B94ItiPSBhEalRO7vKZxZAG8iS0lNUr5uQTxFLuE/Mhzz/8Zz rImmMG6pMTdfxQtq9FSHrfCc7Za3mVSak1RZjkxlJOcrBFxDUYnifGEOzjKbGQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750284998; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=SfH9laT9rv5CsiPPQobeIWYWhtlfzLJUobaE+lgVcrE=; b=jXq8cAhSwjJCXearyvSe4N9BQUW+E3XP0DkL3ZHfdASJO4rYjv3d8DWDrOFvOBfX4kM95a TzW+iIhKwhkRXB3A7uLPIEs1EUWLU8PCDKQsiE2pzRqsYjYrcHt3mReNs7XwAIblIlVPCS 8p4zsN61JjU3wrYVElIsT/4ZqcFPouYKq8vwf+pZ50JhJ6QHfOOAUtsUU/uYaQK84qemDs RNumK3MzAkviGIC/COtNiDlywyuC8vG/TjJ1AMFyLKM9BNopogRPn7qOZtUsnrjkbKsWNK hxwswz0DAEFgwxgNWQ+/Ka4VgOQGm9wuwwrnHjdx9LP1fk1h4PHgfrcg82t5EQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1750284998; a=rsa-sha256; cv=none; b=NuJQaW5eXUVDr6Ma50g4U5/MaHUu1Ttv1wCyHqOnACJA0A8mxwW2pYcJr2KfIgyBQ73pbS eXUMgDQWZGa6jbz5+KF0IP6fi7S1hYX93R7ngjJnyn2MGqa30tdubpiYQI1qFAYW/BOgRC b7hHukiuZDbpK582wucNukb7FyFF6VhxaonEJDD3CiulNiJpfWYqAxkqoVW/UXn1YHv9Mt A+DnWsSfp8HeXALddyYVXZvuLZz7tcLvLLJTkvXE4bWpm5h8zcDhmvyyFLYPvyx89C9BJ/ Cj4FrSR6uZ979kvsz5tV/cdFS3jT5rdUYxbt7eGnRkki4jbSBs2LSp8Bj2jHvg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bMykt5NwRzp4X; Wed, 18 Jun 2025 22:16:38 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 55IMGcep080418; Wed, 18 Jun 2025 22:16:38 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 55IMGcEQ080415; Wed, 18 Jun 2025 22:16:38 GMT (envelope-from git) Date: Wed, 18 Jun 2025 22:16:38 GMT Message-Id: <202506182216.55IMGcEQ080415@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Mateusz Piotrowski <0mp@FreeBSD.org> Subject: git: c29459f901dc - main - tracing.7: Add a single reference point for tracing facilities in FreeBSD List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: 0mp X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: c29459f901dc73e1ebe1e654da2677cc0b7bd296 Auto-Submitted: auto-generated The branch main has been updated by 0mp: URL: https://cgit.FreeBSD.org/src/commit/?id=c29459f901dc73e1ebe1e654da2677cc0b7bd296 commit c29459f901dc73e1ebe1e654da2677cc0b7bd296 Author: Mateusz Piotrowski <0mp@FreeBSD.org> AuthorDate: 2025-06-14 17:38:12 +0000 Commit: Mateusz Piotrowski <0mp@FreeBSD.org> CommitDate: 2025-06-18 22:15:26 +0000 tracing.7: Add a single reference point for tracing facilities in FreeBSD FreeBSD has a fair number of tracing facilities. The new tracing(7) manual page aims to provide a starting point for users to learn about what is available. Reviewed by: christos, bnovkov, markj, ziaee Approved by: christos (mentor), bnovkov (mentor), markj (mentor) Relnotes: yes Differential Revision: https://reviews.freebsd.org/D50854 --- share/man/man7/Makefile | 1 + share/man/man7/tracing.7 | 97 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+) diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 2c4f158280f7..021bf9251bda 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -30,6 +30,7 @@ MAN= arch.7 \ stdint.7 \ sticky.7 \ tests.7 \ + tracing.7 \ tuning.7 MLINKS= intro.7 miscellaneous.7 diff --git a/share/man/man7/tracing.7 b/share/man/man7/tracing.7 new file mode 100644 index 000000000000..0bd64f197084 --- /dev/null +++ b/share/man/man7/tracing.7 @@ -0,0 +1,97 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Mateusz Piotrowski <0mp@FreeBSD.org> +.\" +.Dd June 19, 2025 +.Dt TRACING 7 +.Os +.Sh NAME +.Nm tracing +.Nd introduction to tracing and performance monitoring facilities +.Sh DESCRIPTION +.Fx +features a large variety of tracing and performance monitoring facilities. +Use them to measure performance and +troubleshoot kernel and userland problems both during +.Xr development 7 +and potentially on production systems. +The facilities differ in scope, ease of use, overhead, design, and limitations. +.Ss DTrace +.Xr dtrace 1 +is the most versatile tracing framework available on +.Fx +and is capable of tracing throughout the +.Fx +software stack from the kernel to the applications running in userland. +Refer to +.Xr dtrace 1 +and +.Xr SDT 9 +for more details. +.Pp +.Xr dwatch 1 +is a user-friendly wrapper for DTrace. +It simplifies common DTrace usage patterns and requires less expert knowledge +to operate. +.Pp +.Ss Userland Tracing +.Xr truss 1 +traces system calls. +It uses +.Xr sysdecode 3 +to pretty-print system call arguments and +.Xr ptrace 2 +to trace processes. +.Pp +.Xr ktrace 1 +is useful for debugging user programs. +It enables kernel trace logging for specified processes. +Like +.Xr truss 1 , +it mainly traces system calls, but instead of using +.Xr ptrace 2 , +it asynchronously logs entries to a trace file configured with +.Xr ktrace 2 +(typically +.Pa ktrace.out ) , +and it can log other types of kernel events, such as page faults and name lookups +.Po refer to +.Fl t +in +.Xr ktrace 1 +.Pc . +Also, programs can log to a +.Xr ktrace 1 +stream using the +.Xr utrace 2 +system call. +.Ss Kernel Tracing +.Xr ktr 4 +is a facility for logging strings in the kernel. +It comes in handy for some niche purposes during kernel development. +It lets kernel programmers log events to a global ring buffer, +which can later be dumped using +.Xr ktrdump 8 . +.Ss Hardware Counters +.Pp +.Xr pmcstat 8 , +and its kernel counterpart, +.Xr hwmpc 4 , +is the +.Fx +facility for conducting performance measurements with hardware counters. +.Ss Boot-Time And Shutdown Tracing +.Xr boottrace 4 +is a facility for tracing events at boot and shutdown. +Its target audience are system administrators. +.Pp +.Xr tslog 4 +is a developer-oriented tool for tracing boot-time events. +.Sh HISTORY +The +.Nm +manual page was written by +.An Mateusz Piotrowski Aq Mt 0mp@FreeBSD.org . +It first appeared in +.Fx 15.0 .