DTrace for System Tracing
- Product:
- Oracle Linux
- Document Type:
- Using DTrace for System Tracing Reference Guide
- Version:
- F76721-03 (May 2025)
- Last Publish Date:
- May 2025
- Tools Used:
- DITA XML, Oxygen XML Editor, Git
Overview
Oracle Linux: Using DTrace for System Tracing is the definitive reference guide for DTrace, a powerful dynamic tracing framework for Oracle Linux with the Unbreakable Enterprise Kernel (UEK). This guide documents DTrace’s complete feature set, including the D programming language, probe providers, aggregation functions, and advanced tracing capabilities for production system analysis. As the primary technical writer for the latest update (F76721-03, May 2025), I restructured the entire guide using DITA XML data types and incorporated documentation for the new eBPF-based DTrace implementation.
Target Audience
Administrators, developers, and performance engineers using DTrace for system analysis and troubleshooting on Oracle Linux. Assumes familiarity with Linux system administration and performance analysis concepts.
My Contributions
Documentation Restructuring
Migrated legacy content to DITA XML data types, transforming existing documentation into structured DITA architecture. Implemented topic-based authoring by decomposing monolithic chapters into modular, reusable DITA topics. Designed information architecture creating DITA map structure optimizing content organization. Established content reuse strategy implementing conrefs and content references for multi-version documentation.
New Feature Documentation
Documented the new eBPF-based DTrace implementation leveraging Linux kernel eBPF facilities. Updated probe providers for compatibility with modern Linux kernels. Added coverage for Oracle Linux 8, 9, and 10 with UEK 6, 7, and 8. Documented support for both x86_64 and aarch64 architectures.
Technical Accuracy and Testing
Tested all DTrace examples on multiple Oracle Linux versions and kernel releases. Revised D programming examples for compatibility with new implementation. Validated all dtrace command options and output formats. Confirmed interaction with modern Linux tracing facilities.
Documentation Challenges
Challenge 1: Documenting Major Implementation Change
The new DTrace implementation represents a fundamental architectural shift from kernel patches to eBPF-based tracing. Documentation needed to explain this transition while maintaining continuity for existing users.
Solution: Created clear sections distinguishing the new implementation from earlier versions. Documented functional compatibility ensuring existing DTrace scripts continue working. Explained eBPF integration benefits (no kernel patches required, modern Linux integration).
Challenge 2: DITA XML Data Typing
The previous guide mixed data types and didn’t enforce information data typing. Reworking the content to use DITA data types (concept, task, reference) required restructuring content while preserving technical accuracy and completeness.
Solution: Analyzed existing content structure to identify natural topic boundaries. Broke monolithic chapters into concept, task, and reference topics. Established topic relationships and cross-references in DITA maps. Compared output from DITA build against original documentation to ensure no content loss.
DITA XML Architecture
Designed DITA map structure with progressive disclosure: high-level concepts first, followed by architectural details, with clear cross-references. Used concept topics for technology explanations, task topics for step-by-step procedures, and reference topics for command syntax and parameters. Implemented conrefs for common terminology and keyrefs for platform names and version numbers.
Technical Approach
Reviewed existing documentation and compared with new implementation features. Identified new features requiring documentation and deprecated features to remove. Created DITA topic structure and map organization. Converted legacy content to DITA topics with appropriate topic types. Wrote documentation for new eBPF-based features. Tested all D program examples on target platforms. Coordinated reviews with DTrace development team.