AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-logs

Add PostHog log capture to track application logs. Use after implementing features or reviewing PRs to ensure meaningful log events are captured with structured properties. Also handles initial OTLP exporter setup if not yet configured.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-logs at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 19

references/ios.md

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

iOS Logs installation

Canonical URL: https://posthog.com/docs/logs/installation/ios

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

The PostHog iOS SDK has built-in support for capturing structured Logs from iOS, macOS, tvOS, watchOS, and visionOS apps. The SDK handles OTLP encoding, batching, on-disk persistence across app restarts, and lifecycle integration. You just call PostHogSDK.shared.captureLog(...) or PostHogSDK.shared.logger?.{trace,debug,info,warn,error,fatal}(...).

Manual capture only. Logs are emitted by your code. The SDK does not autocapture system log streams (os_log, Logger, print).

Minimum version: [email protected] or later. Run pod update PostHog (CocoaPods) or update the package version in Xcode (Swift Package Manager).

  1. 1

    Install posthog-ios

    Required

    If you haven't installed posthog-ios yet, follow the steps below. For full details, see the iOS SDK guide.

    PostHog is available through CocoaPods or you can add it as a Swift Package Manager based dependency.

    CocoaPods

    Podfile

    pod "PostHog", "~> 3.59.3"
    

    Swift Package Manager

    Add PostHog as a dependency in your Xcode project "Package Dependencies" and select the project target for your app, as appropriate.

    For a Swift Package Manager based project, add PostHog as a dependency in your Package.swift file's Package dependencies section:

    Package.swift

    dependencies: [
      .package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.59.3")
    ],
    

    and then as a dependency for the Package target utilizing PostHog:

    Package.swift

    .target(
        name: "myApp",
        dependencies: [.product(name: "PostHog", package: "posthog-ios")]),
    

    Configuration

    Configuration is done through the PostHogConfig object. Here's a basic configuration example to get you started.

    You can find more advanced configuration options in the configuration page.

    UIKit

    import Foundation
    import PostHog
    import UIKit
    
    class AppDelegate: NSObject, UIApplicationDelegate {
        func application(_: UIApplication, didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
            let POSTHOG_PROJECT_TOKEN = "<ph_project_token>"
            // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
            let POSTHOG_HOST = "https://us.i.posthog.com"
    
            let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST)
            PostHogSDK.shared.setup(config)
    
            return true
        }
    }
    

    SwiftUI

    import SwiftUI
    import PostHog
    
    @main
    struct YourGreatApp: App {
    
        // Add PostHog to your app's initializer.
        // If using UIApplicationDelegateAdaptor, see the UIKit tab.
    
        init() {
    
            let POSTHOG_PROJECT_TOKEN = "<ph_project_token>"
            // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
            let POSTHOG_HOST = "https://us.i.posthog.com"
    
            let config = PostHogConfig(projectToken: POSTHOG_PROJECT_TOKEN, host: POSTHOG_HOST)
            PostHogSDK.shared.setup(config)
    
        }
    
        var body: some Scene {
            WindowGroup {
                ContentView()
            }
        }
    }
    
  2. 2

    Configure logs in your PostHogConfig

    Required

    Configure Logs through config.logs before calling setup(_:). All fields are optional; defaults are tuned for mobile (cellular bandwidth, battery, OS lifecycle).

    import PostHog
    
    let config = PostHogConfig(projectToken: "<ph_project_token>", host: "https://us.i.posthog.com")
    config.logs.serviceName = "my-app"        // OTLP service.name – shown in the Logs UI
    config.logs.environment = "production"    // OTLP deployment.environment
    config.logs.serviceVersion = "1.2.3"      // OTLP service.version
    
    PostHogSDK.shared.setup(config)
    

    These resource attributes are captured at setup(_:) and apply to every batch. Mutating config.logs after setup has no effect.

  3. 3

    Capture logs

    Required

    Use PostHogSDK.shared.logger for the per-level convenience API, or PostHogSDK.shared.captureLog for full control over level, attributes, and trace context.

    // Per-level convenience methods – Optional, since logger is created at setup
    PostHogSDK.shared.logger?.info("checkout completed", attributes: ["order_id": "ord_789", "amount_cents": 4999])
    PostHogSDK.shared.logger?.warn("payment retry", attributes: ["attempt": 2])
    PostHogSDK.shared.logger?.error("payment failed", attributes: ["code": "E001"])
    
    // Lower-level API for custom severity / trace context
    PostHogSDK.shared.captureLog(
        "checkout failed",
        level: .error,
        attributes: ["order_id": "ord_789", "step": "auth"],
        traceId: "4bf92f3577b34da6a3ce929d0e0e4736",  // optional W3C trace context (32 hex chars)
        spanId: "00f067aa0ba902b7"                    // optional W3C span (16 hex chars)
    )
    

    Available severity levels: .trace, .debug, .info, .warn, .error, .fatal.

    Records are buffered, batched, persisted to disk, and flushed automatically – every 30 seconds, when the buffer hits the threshold, when the app moves to the background, or on PostHogSDK.shared.flush(). flush() drains events, Session Replay, and Logs together.

    Each record is automatically tagged with the current distinct ID, session ID, current screen, app foreground/background state, and active Feature Flags at the moment of capture.

  4. 4

    Test your setup

    Recommended

    1. Capture a test log from your app:

      PostHogSDK.shared.logger?.info("hello from iOS")
      PostHogSDK.shared.flush()
      
    2. Open the PostHog Logs UI.

    3. Filter by service.name = 'my-app' (or whatever value you set above).

    You should see your record arrive within a few seconds.

    View your Logs in PostHog

  5. 5

    Tune buffering, rate cap, and resource attributes

    Optional

    The logs config has knobs for high-volume apps:

    let config = PostHogConfig(projectToken: "<ph_project_token>")
    config.logs.serviceName = "my-app"
    config.logs.flushIntervalSeconds = 5            // default 30
    config.logs.maxBufferSize = 200                 // default 1000
    config.logs.maxBatchSize = 50                   // default 50
    config.logs.flushAt = 20                        // default 20
    config.logs.rateCapMaxLogs = 5000               // default 500
    config.logs.rateCapWindowSeconds = 60           // default 10
    config.logs.resourceAttributes = ["host.name": "device-01"]
    PostHogSDK.shared.setup(config)
    

    Full configuration reference:

    | Field | Default | What it does | | --- | --- | --- | | serviceName | bundle identifier | OTLP service.name resource attribute | | serviceVersion | CFBundleShortVersionString | OTLP service.version resource attribute | | environment | nil | OTLP deployment.environment resource attribute | | resourceAttributes | [:] | Extra OTLP resource attributes (SDK keys win on collision) | | flushIntervalSeconds | 30 | Periodic flush interval | | flushAt | 20 | Buffer threshold that triggers an automatic flush | | maxBatchSize | 50 | Max records per outbound POST (halved on 413) | | maxBufferSize | 1000 | Max records held on disk before FIFO eviction | | rateCapMaxLogs | 500 | Max records per rateCapWindowSeconds window. Set to 0 to disable. | | rateCapWindowSeconds | 10 | Rate-cap tumbling window length |

    All of the above are captured at setup(_:); mutating them later has no effect. Defaults are tuned for cellular-aware mobile apps. Raise rateCapMaxLogs and maxBufferSize for high-volume scenarios.

  6. 6

    Filter or redact with beforeSend

    Optional

    beforeSend runs synchronously before the rate cap, so dropped records don't consume the per-window budget. Use it for redaction, sampling, or filtering by level. Each block receives a mutable PostHogLogRecord and returns either the (possibly mutated) record or nil to drop it.

    config.logs.setBeforeSend({ record in
        // Drop debug logs in production
        if record.level == .debug { return nil }
    
        // Redact secrets in the body
        record.body = record.body.replacingOccurrences(
            of: #"api_key=\S+"#,
            with: "api_key=[REDACTED]",
            options: .regularExpression
        )
        return record
    })
    

    Pass an array (or a comma-separated list) of blocks to compose a chain – evaluated left-to-right. Returning nil from any block short-circuits and drops the record. Setting record.body to an empty string also drops the record.

    From Objective-C, wrap each closure in a BoxedBeforeSendLogBlock:

    [posthogConfig.logs setBeforeSend:@[
        [[BoxedBeforeSendLogBlock alloc] initWithBlock:^PostHogLogRecord * _Nullable(PostHogLogRecord * record) {
            return [record.body containsString:@"secret"] ? nil : record;
        }]
    ]];
    
  7. Next steps

    Checkpoint

    What you can do with your logs

    | Action | Description | | --- | --- | | Why you need logs | What logs show you that nothing else does | | Search logs | Use the search interface to find specific log entries | | Filter by level | Filter by INFO, WARN, ERROR, etc. | | Link session replay | Connect logs to users and session replays by passing posthogDistinctId and sessionId | | Link logs to a person | Surface every log emitted on behalf of a user on their PostHog person profile | | Logging best practices | Learn what to log, how to structure logs, and patterns that make logs useful in production |

    Troubleshoot common issues