references/flutter.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Flutter Logs installation
Canonical URL: https://posthog.com/docs/logs/installation/flutter
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.posthog.cominstead ofhttps://us.posthog.comorhttps://app.posthog.com(app host for links).
On this page
- Install posthog_flutter
- Configure logs in your PostHogConfig
- Capture logs
- Test your setup
- Tune buffering, rate cap, and resource attributes
- Filter or redact with beforeSend
- Next steps
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 (
debugPrint, ordart:developer'slog).
Minimum version:
posthog_flutter5.27.0or later (the release that adds Logs support). On mobile it pulls inposthog-android3.48.0or later automatically.
-
1
Install posthog_flutter
Required
If you haven't installed
posthog_flutteryet, 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_flutterto yourpubspec.yaml:pubspec.yaml
# rest of your code dependencies: flutter: sdk: flutter posthog_flutter: ^5.26.0 # rest of your codeThen 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_INITmode.Android setup
There are 2 ways of initializing the SDK, automatically and manually.
Automatically:
Add your PostHog configuration to your
AndroidManifest.xmlfile located in theandroid/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.xmlfile located in theandroid/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
23inandroid/app/build.gradle:android/app/build.gradle
// rest of your config defaultConfig { minSdkVersion 23 // rest of your config } // rest of your configiOS setup
There are 2 ways of initializing the SDK, automatically and manually.
The SDK supports both CocoaPods and Swift Package Manager (SPM). 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.plistfile located in theios/Runnerdirectory: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.plistfile located in theios/Runnerdirectory: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.
For CocoaPods projects, set it in your
Podfile:ios/Podfile
platform :ios, '13.0' # rest of your configFor Swift Package Manager projects without a
Podfile, set the Minimum Deployments version to iOS 13.0 for theRunnertarget in Xcode (Runner > General > Minimum Deployments). After you change Minimum Deployments, regenerate the iOS project's configuration files:flutter build ios --config-onlyDart 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:
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
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) in the<header>of yourweb/index.htmlfile. 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
<!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 || [], Object.defineProperty(u, "toString", { configurable: !0, enumerable: !0, writable: !0, value: function (t) { var e = "posthog"; return ("posthog" !== a && (e += "." + a), t || (e += " (stub)"), e); }, }), Object.defineProperty(u.people, "toString", { configurable: !0, enumerable: !0, writable: !0, value: 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 getFeatureFlagResult 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-08-30", }); </script> </head> <!-- other elements --> </html>For more information please check: /docs/libraries/js
-
2
Configure logs in your PostHogConfig
Required
Configure Logs through
config.logsConfigbefore callingPosthog().setup(...). All fields are optional; unset fields fall back to the native defaults, which are tuned for mobile (cellular bandwidth, battery, app lifecycle).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-jsinstance, soconfig.logsConfigis not applied on web. Configure your log options in theposthog.init({...})call in yourweb/index.htmlinstead.captureLogandloggerstill work on web (they are forwarded toposthog-js), andbeforeSendstill runs (in Dart) on web. Web also requires a recentposthog-jsbuild that exposescaptureLog.For example, set the same service identity on the
posthog-jssnippet inweb/index.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-jslogs config. -
3
Capture logs
Required
Use
Posthog().loggerfor the per-level convenience API, orPosthog().captureLogfor full control over level, attributes, and trace context.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, andfatal, each taking aString bodyand an optionalMap<String, Object>of attributes. Available severity levels forcaptureLogarePostHogLogSeverity.trace,.debug,.info,.warn,.error, and.fatal.The optional W3C trace fields (
traceId,spanId,traceFlags) are available oncaptureLogonly, not on theloggerfacade.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.fullis tagged instead of screen name and app state. -
4
Test your setup
Recommended
-
Capture a test log from your app:
Posthog().logger.info('hello from Flutter'); Posthog().flush(); -
Open the PostHog Logs UI.
-
Filter by
service.name = 'my-app'(or whatever value you set above).
You should see your record arrive within a few seconds.
-
-
5
Tune buffering, rate cap, and resource attributes
Optional
The
logsConfighas knobs for high-volume apps: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) | OTLPservice.nameresource attribute | |serviceVersion| app version | OTLPservice.versionresource attribute | |environment| none | OTLPdeployment.environmentresource 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 perrateCapWindow. Set to0to disable. | |rateCapWindow|10s| Rate-cap window length |Defaults are tuned for cellular-aware mobile apps. Raise
rateCapMaxLogsandmaxBufferSizefor high-volume scenarios.On web, these fields are not applied – configure them in your
posthog.init({...})call inweb/index.htmlinstead. -
6
Filter or redact with beforeSend
Optional
Use
config.logsConfig.beforeSendfor redaction, sampling, or filtering by level. It is aList<BeforeSendLogCallback>, where each callback is aFutureOr<PostHogLogRecord?> Function(PostHogLogRecord). Callbacks run in Dart on all platforms (including web), evaluated left-to-right. Each callback receives a mutablePostHogLogRecord(with mutablebody,level, andattributes) and returns either the (possibly mutated) record ornullto drop it. Callbacks can be synchronous or asynchronous.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
nullfrom any callback short-circuits and drops the record. Settingrecord.bodyto 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 passingposthogDistinctIdandsessionId| | 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 |