Flutter Logs installation

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.

Install posthog_flutter

Required

If you haven't installed posthog_flutter yet, follow the steps below. For full details, see the Flutter SDK guide.

PostHog is available for install via Pub.

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
# 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
<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" android:value="https://us.i.posthog.com" />  <!-- usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com' -->
        <!-- com.posthog.posthog.CAPTURE_APPLICATION_LIFECYCLE_EVENTS is enabled by default since version 5.23.0 (previously named TRACK_APPLICATION_LIFECYCLE_EVENTS, which still works as an alias) -->
        <meta-data android:name="com.posthog.posthog.DEBUG" android:value="true" />
    </application>
</manifest>

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
<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
// 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.

You'll need to have Cocoapods installed.

Automatically:

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

ios/Runner/Info.plist
<?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>
    <string><ph_project_token></string>
    <key>com.posthog.posthog.POSTHOG_HOST</key>
    <string>https://us.i.posthog.com</string>
    <!-- com.posthog.posthog.CAPTURE_APPLICATION_LIFECYCLE_EVENTS is enabled by default since version 5.23.0 -->
    <key>com.posthog.posthog.DEBUG</key>
    <true/>
</dict>
</plist>

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
<?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>
</plist>

In both cases, you'll need to set the minimum platform version to iOS 13.0 in your Podfile:

ios/Podfile
platform :ios, '13.0'

# rest of your config

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
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;
  // captureApplicationLifecycleEvents is enabled by default since version 5.23.0
  config.host = 'https://us.i.posthog.com';
  await Posthog().setup(config);
  runApp(MyApp());
}

Web setup

For Web, add your Web snippet (which you can find in your project settings) in the <header> of your web/index.html file:

web/index.html
<!DOCTYPE html>
<html>

<head>
  <!-- ... other head elements ... -->

  <script async>
    !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys getNextSurveyStep onSessionId".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
    posthog.init('<ph_project_token>', {
      api_host:'https://us.i.posthog.com', // 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
      defaults: '2026-01-30',
    })
  </script>
</head>

<!-- other elements -->

</html>

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

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
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
config.logsConfig.environment = 'production';    // OTLP deployment.environment
config.logsConfig.serviceVersion = '1.2.3';      // OTLP service.version
await Posthog().setup(config);

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 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
<script>
  posthog.init('<ph_project_token>', {
    api_host: 'https://us.i.posthog.com',
    logs: {
      serviceName: 'my-app',
      environment: 'production',
      serviceVersion: '1.2.3',
    },
  })
</script>

See the JavaScript Logs installation guide for the full posthog-js logs config.

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
import 'package:posthog_flutter/posthog_flutter.dart'; // Per-level convenience methods Posthog().logger.info('checkout completed', {'order_id': 'ord_789', 'amount_cents': 4999}); Posthog().logger.warn('payment retry', {'attempt': 2}); Posthog().logger.error('payment failed', {'code': 'E001'}); // Lower-level API for custom severity / trace context Posthog().captureLog( body: 'checkout failed', level: PostHogLogSeverity.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) traceFlags: 1, );
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.
4
Test your setup
Recommended
1. Capture a test log from your app:
  Dart
  Posthog().logger.info('hello from Flutter'); Posthog().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

Tune buffering, rate cap, and resource attributes

Optional

The logsConfig has knobs for high-volume apps:

Dart
final config = PostHogConfig('<ph_project_token>');
config.logsConfig.serviceName = 'my-app';
config.logsConfig.flushInterval = Duration(seconds: 5);      // default 30s
config.logsConfig.maxBufferSize = 200;                       // default 1000
config.logsConfig.maxBatchSize = 50;                         // default 50
config.logsConfig.flushAt = 20;                              // default 20
config.logsConfig.rateCapMaxLogs = 5000;                     // default 500
config.logsConfig.rateCapWindow = Duration(seconds: 60);     // default 10s
config.logsConfig.resourceAttributes = {'host.name': 'device-01'};
await Posthog().setup(config);

Full configuration reference:

Field	Default	What it does
`serviceName`	app bundle id (iOS) / app namespace (Android)	OTLP `service.name` resource attribute
`serviceVersion`	app version	OTLP `service.version` resource attribute
`environment`	none	OTLP `deployment.environment` resource attribute
`resourceAttributes`	`{}`	Extra OTLP resource attributes
`flushInterval`	`30s`	Periodic flush interval
`flushAt`	`20`	Buffer threshold that triggers an automatic flush
`maxBatchSize`	`50`	Max records per outbound POST
`maxBufferSize`	`1000`	Max records held on disk before FIFO eviction
`rateCapMaxLogs`	`500`	Max records per `rateCapWindow`. Set to `0` to disable.
`rateCapWindow`	`10s`	Rate-cap window length

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.

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
config.logsConfig.beforeSend = [ (record) { // Drop debug logs in production if (record.level == PostHogLogSeverity.debug) return null; // Redact a sensitive attribute record.attributes?.remove('password'); return record; }, // Compose a chain – callbacks run left-to-right (record) => record.body.contains('secret') ? null : record, ];
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).

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

Flutter Logs installation

Install posthog_flutter

Configuration

Android setup

iOS setup

Dart setup (For manual step only)

Web setup

Configure logs in your PostHogConfig

Capture logs

Test your setup

Tune buffering, rate cap, and resource attributes

Filter or redact with beforeSend

Next steps

Community questions

Was this page useful?