Flutter

The PostHog Flutter SDK has built-in support for capturing structured Logs from your Flutter app across mobile and web. The SDK handles the OTLP encoding, batching, and flushing — and on mobile, on-disk persistence across app restarts and app-lifecycle integration (web buffers in memory via posthog-js). You just call Posthog().captureLog(...) or Posthog().logger.{trace,debug,info,warn,error,fatal}(...).

Manual capture only. Logs are emitted by your code. The SDK does not autocapture system log streams (print, debugPrint, or dart:developer‘s log).

Minimum version: posthog_flutter 5.27.0 or later (the release that adds Logs support). On mobile it pulls in posthog-android 3.48.0 or later automatically.

1. 1

   Install posthog_flutter

   Required

   If you haven’t installed posthog_flutter yet, follow the steps below. For full details, see the Flutter SDK guide (opens in a new tab).

   PostHog is available for install via Pub (opens in a new tab).

   Configuration

   Set your PostHog project token and enable automatic event tracking if you want the library to capture lifecycle events for you.

   Remember that the application lifecycle events won’t have any special context set for you by the time it is initialized. If you are using a self-hosted instance of PostHog you will need to have the public hostname or IP for your instance as well.

   To start, add posthog_flutter to your pubspec.yaml:

   pubspec.yaml

   yamlCopy

   # rest of your code
   
   dependencies:
     flutter:
       sdk: flutter
     posthog_flutter: ^5.26.0
   
   # rest of your code

   Then complete the setup for each platform:

   For Session Replay and Surveys, you must set up the SDK manually by disabling the com.posthog.posthog.AUTO_INIT mode.

   Android setup

   There are 2 ways of initializing the SDK, automatically and manually.

   Automatically:

   Add your PostHog configuration to your AndroidManifest.xml file located in the android/app/src/main:

   android/app/src/main/AndroidManifest.xml

   xmlCopy

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
       <application>
           <!-- ... other configuration ... -->
           <meta-data android:name="com.posthog.posthog.PROJECT_TOKEN" android:value="<ph_project_token>" />
           <meta-data android:name="com.posthog.posthog.POSTHOG_HOST"
   
   
   
   

   Or manually (more control and more configurations available):

   Add your PostHog configuration to your AndroidManifest.xml file located in the android/app/src/main:

   android/app/src/main/AndroidManifest.xml

   xmlCopy

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="your.package.name">
       <application>
           <!-- ... other configuration ... -->
           <meta-data android:name="com.posthog.posthog.AUTO_INIT" android:value="false" />
       </application>
   </manifest>

   In both cases, you’ll also need to update the minimum Android SDK version to 23 in android/app/build.gradle:

   android/app/build.gradle

   kotlinCopy

   // rest of your config
   
       defaultConfig {
           minSdkVersion 23
           // rest of your config
       }
   
   // rest of your config

   iOS setup

   There are 2 ways of initializing the SDK, automatically and manually.

   The SDK supports both CocoaPods (opens in a new tab) and Swift Package Manager (SPM) (opens in a new tab). Flutter 3.44 and later enable SPM by default. On earlier versions, or if you disabled SPM, enable it with flutter config --enable-swift-package-manager.

   Automatically:

   Add your PostHog configuration to the Info.plist file located in the ios/Runner directory:

   ios/Runner/Info.plist

   xmlCopy

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <!-- rest of your configuration -->
       <key>com.posthog.posthog.PROJECT_TOKEN</key>
       <
   
   
   
   
   
   
   

   Or manually (more control and more configurations available):

   Add your PostHog configuration to the Info.plist file located in the ios/Runner directory:

   ios/Runner/Info.plist

   xmlCopy

   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
   <plist version="1.0">
   <dict>
       <!-- rest of your configuration -->
       <key>com.posthog.posthog.AUTO_INIT</key>
       <false/>
   </dict
   

   In both cases, you’ll need to set the minimum platform version to iOS 13.0.

   For CocoaPods projects, set it in your Podfile:

   ios/Podfile

   yamlCopy

   platform :ios, '13.0'
   # rest of your config

   For Swift Package Manager projects without a Podfile, set the Minimum Deployments version to iOS 13.0 for the Runner target in Xcode (Runner > General > Minimum Deployments). After you change Minimum Deployments, regenerate the iOS project’s configuration files:

   Terminal

   bashCopy

   flutter build ios --config-only

   Dart setup (For manual step only)

   If you followed the automatic SDK setup, then there’s no more configuration needed in Dart.

   If you followed the manual SDK setup:

   Dart

   dartCopy

   import 'package:flutter/material.dart';
   
   import 'package:posthog_flutter/posthog_flutter.dart';
   
   Future<void> main() async {
     // init WidgetsFlutterBinding if not yet
     WidgetsFlutterBinding.ensureInitialized();
     final config = PostHogConfig('<ph_project_token>');
     config.debug = true;
   
   
   
   
   

   Web setup

   If your project has a web/ directory, this step is required. Posthog().setup() is a no-op on web, so a web build without the snippet below captures nothing.

   Add your Web snippet (which you can find in your project settings (opens in a new tab)) in the <header> of your web/index.html file. Write your project token into the snippet as a literal string. It’s public, the same token ships to every visitor, and it needs no build-time or deploy-time injection:

   web/index.html

   htmlCopy

   <!DOCTYPE html>
   <html
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

   For more information please check: /docs/libraries/js

2. 2

   Configure logs in your PostHogConfig

   Required

   Configure Logs through config.logsConfig before calling Posthog().setup(...). All fields are optional; unset fields fall back to the native defaults, which are tuned for mobile (cellular bandwidth, battery, app lifecycle).

   Dart

   dartCopy

   final config = PostHogConfig('<ph_project_token>');
   config.host = 'https://us.i.posthog.com';
   config.logsConfig.serviceName = 'my-app';        // OTLP service.name – shown in the Logs UI
   
   
   

3. 3

   Capture logs

   Required

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

   Dart

   dartCopy

   import 'package:posthog_flutter/posthog_flutter.dart';
   
   // Per-level convenience methods
   Posthog().logger.info('checkout completed', {'order_id': 'ord_789'
   
   
   
   
   
   
   
   
   
   
   
   

4. 4

   Test your setup

   Recommended

   1. Capture a test log from your app:

      Dart

      dartCopy

      Posthog().logger.info('hello from Flutter');
      Posthog().flush();

   2. Open the PostHog Logs UI (opens in a new tab).

   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 logsConfig has knobs for high-volume apps:

   Dart

   dartCopy

   final config = PostHogConfig('<ph_project_token>');
   config.logsConfig.serviceName = 'my-app';
   config.logsConfig.flushInterval = Duration
   
   
   
   
   
   
   

6. 6

   Filter or redact with beforeSend

   Optional

   Use config.logsConfig.beforeSend for redaction, sampling, or filtering by level. It is a List<BeforeSendLogCallback>, where each callback is a FutureOr<PostHogLogRecord?> Function(PostHogLogRecord). Callbacks run in Dart on all platforms (including web), evaluated left-to-right. Each callback receives a mutable PostHogLogRecord (with mutable body, level, and attributes) and returns either the (possibly mutated) record or null to drop it. Callbacks can be synchronous or asynchronous.

   Dart

   dartCopy

   config.logsConfig.beforeSend = [
     (record) {
       // Drop debug logs in production
       if (record.level == PostHogLogSeverity
   
   
   
   
   
   
   
   

7. Next steps

   Checkpoint

   What you can do with your logs

   Action	Description
   Why you need logs (opens in a new tab)	What logs show you that nothing else does
   Search logs (opens in a new tab)	Use the search interface to find specific log entries
   Filter by level	Filter by INFO, WARN, ERROR, etc.
   Link session replay

Still have questions?

Ask PostHog AI

Was this page useful?

HelpfulCould be better

These resource attributes are captured at setup(...) and apply to every batch.

Web behavior. On Flutter Web, the SDK attaches to an already-initialized posthog-js (opens in a new tab) instance, so config.logsConfig is not applied on web. Configure your log options in the posthog.init({...}) call in your web/index.html instead. captureLog and logger still work on web (they are forwarded to posthog-js), and beforeSend still runs (in Dart) on web. Web also requires a recent posthog-js build that exposes captureLog.

For example, set the same service identity on the posthog-js snippet in web/index.html:

HTML

See the JavaScript Logs installation guide (opens in a new tab) for the full posthog-js logs config.

The per-level facade methods are trace, debug, info, warn, error, and fatal, each taking a String body and an optional Map<String, Object> of attributes. Available severity levels for captureLog are PostHogLogSeverity.trace, .debug, .info, .warn, .error, and .fatal.

The optional W3C trace fields (traceId, spanId, traceFlags) are available on captureLog only, not on the logger facade.

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 Posthog().flush(). flush() drains events, Session Replay, and Logs together.

Each record is automatically tagged with the current distinct ID, session ID, active feature flags, and (on mobile) the current screen and app foreground/background state at the moment of capture. On web, url.full is tagged instead of screen name and app state.

Full configuration reference:

Defaults are tuned for cellular-aware mobile apps. Raise rateCapMaxLogs and maxBufferSize for high-volume scenarios.

On web, these fields are not applied – configure them in your posthog.init({...}) call in web/index.html instead.

Returning null from any callback short-circuits and drops the record. Setting record.body to an empty or whitespace-only string also drops the record. A callback that throws is logged and the record is dropped (fail-closed).

Troubleshoot common issues (opens in a new tab)