logging-guidelines

Logging Guidelines & Telemetry Capture

Overview

The DuckDuckGo browser apps for iOS and macOS leverage Apple's Unified Logging System for capturing telemetry and debugging information. This system enables efficient tracking of app behavior, issue diagnosis, and performance monitoring in a structured and privacy-conscious manner.

Key Benefits:

• Privacy-first: Built-in privacy controls for sensitive data
• Performance: Optimized for minimal overhead
• Integration: Native Apple ecosystem support
• Debugging: Rich contextual information and filtering

How to Log

Using the Logger Class

We utilize the Logger class from Apple's os framework for all logging activities:

import os

// Basic logging examples
Logger.yourFeatureName.debug("Something to log, with info: \(infoVar)")
Logger.anotherFeatureName.error("Some error happened: \(error.localizedDescription, privacy: .public)")
Logger.networking.info("API request completed for endpoint: \(endpoint, privacy: .public)")
Logger.performance.debug("Operation took \(duration)ms to complete")

Creating Custom Loggers

Single Feature Logger

For new features, create a dedicated logger file named Logger+YourFeatureName.swift:

import os

public extension Logger {
    static var yourFeatureName: Logger = { 
        Logger(subsystem: "Your Feature Name", category: "") 
    }()
    
    static var anotherFeatureName: Logger = { 
        Logger(subsystem: "Another feature name", category: "Subsystem in the feature") 
    }()
}

Multiple Feature Loggers

For related features, add to existing logger extensions (e.g., Logger+Multiple.swift):

import os

public extension Logger {
    // Networking loggers
    static var networking: Logger = { 
        Logger(subsystem: "Networking", category: "API") 
    }()
    
    static var cache: Logger = { 
        Logger(subsystem: "Networking", category: "Cache") 
    }()
    
    // UI loggers  
    static var tabManagement: Logger = { 
        Logger(subsystem: "UI", category: "Tab Management") 
    }()
    
    static var bookmarks: Logger = { 
        Logger(subsystem: "UI", category: "Bookmarks") 
    }()
}