references/android.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Android Logs installation
Canonical URL: https://posthog.com/docs/logs/installation/android
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install posthog-android
- Configure logs in your PostHogAndroidConfig
- Capture logs
- Test your setup
- Tune buffering, rate cap, and resource attributes
- Filter or redact with beforeSend
- Next steps
The PostHog Android SDK has built-in support for capturing structured Logs from Android apps. The SDK handles the OTLP encoding, batching, on-disk persistence across app restarts, and lifecycle integration. You just call 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 (
Log.d,Logcat,Timber).
Minimum version:
com.posthog:[email protected]or later. Bump the dependency in yourbuild.gradle(orbuild.gradle.kts) and re-sync.
-
1
Install posthog-android
Required
If you haven't installed
posthog-androidyet, follow the Android SDK installation guide. -
2
Configure logs in your PostHogAndroidConfig
Required
Configure Logs through
config.logsbefore callingPostHogAndroid.setup(...). All fields are optional; defaults are tuned for mobile (cellular bandwidth, battery, app lifecycle).val config = PostHogAndroidConfig( apiKey = "<ph_project_token>", host = "https://us.i.posthog.com", ).apply { logs.serviceName = "my-app" // OTLP service.name – shown in the Logs UI logs.environment = "production" // OTLP deployment.environment logs.serviceVersion = "1.2.3" // OTLP service.version }These resource attributes are captured at
setup(...)and apply to every batch. Mutatingconfig.logs.serviceName,environment,serviceVersion, orresourceAttributesafter setup has no effect. -
3
Capture logs
Required
Use
PostHog.loggerfor the per-level convenience API.import com.posthog.PostHog import com.posthog.logs.PostHogLogSeverity // Per-level convenience methods PostHog.logger.info("checkout completed", mapOf("order_id" to "ord_789", "amount_cents" to 4999)) PostHog.logger.warn("payment retry", mapOf("attempt" to 2)) PostHog.logger.error("payment failed", mapOf("code" to "E001")) // Generic entry point for a runtime severity (e.g. mapping a Timber priority) PostHog.logger.log("rendered cart", severity = PostHogLogSeverity.DEBUG)Available severity levels:
TRACE,DEBUG,INFO,WARN,ERROR,FATAL.If you need W3C trace correlation, call
PostHog.captureLog(...)directly and passtraceId,spanId, andtraceFlags.PostHog.captureLog( "payment failed", severity = PostHogLogSeverity.ERROR, attributes = mapOf("code" to "PAY_3001"), traceId = "4bf92f3577b34da6a3ce929d0e0e4736", spanId = "00f067aa0ba902b7", traceFlags = 0x01, )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, current screen, app foreground/background state, and active Feature Flags at the moment of capture.
From Java:
import com.posthog.PostHog; import com.posthog.logs.PostHogLogSeverity; import java.util.Map; PostHog.Companion.getLogger().info("checkout opened", null); PostHog.Companion.getLogger().error( "payment failed", Map.of("amount_cents", 1999, "currency", "USD") ); -
4
Test your setup
Recommended
-
Capture a test log from your app:
PostHog.logger.info("hello from Android") 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
logsconfig has knobs for high-volume apps:val config = PostHogAndroidConfig(apiKey = "<ph_project_token>").apply { logs.serviceName = "my-app" logs.flushIntervalSeconds = 5 // default 30 logs.maxBufferSize = 200 // default 1000 logs.maxBatchSize = 50 // default 50 logs.flushAt = 20 // default 20 logs.rateCapMaxLogs = 5000 // default 500 logs.rateCapWindowSeconds = 60 // default 10 logs.resourceAttributes = mapOf("host.name" to "device-01") } PostHogAndroid.setup(this, config)Full configuration reference:
| Field | Default | What it does | | --- | --- | --- | |
serviceName| app package id | OTLPservice.nameresource attribute | |serviceVersion|BuildConfig.VERSION_NAME| OTLPservice.versionresource attribute | |environment|null| OTLPdeployment.environmentresource 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 perrateCapWindowSecondswindow. Set to0to disable. | |rateCapWindowSeconds|10| Rate-cap tumbling window length |serviceName,serviceVersion,environment,resourceAttributes,flushAt, andmaxBatchSizeare captured atsetup(...); mutating them later has no effect.flushIntervalSeconds,maxBufferSize, and rate-cap fields are re-read at runtime. Defaults are tuned for cellular-aware mobile apps. RaiserateCapMaxLogsandmaxBufferSizefor high-volume scenarios. -
6
Filter or redact with beforeSend
Optional
beforeSendruns 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 hook receives an immutablePostHogLogRecordand returns either a (possibly modified) record ornullto drop it.config.logs.addBeforeSend { record -> // Drop debug logs in production if (record.level == PostHogLogSeverity.DEBUG) return@addBeforeSend null // Redact secrets in the body record.copy(body = record.body.replace(Regex("api_key=\\S+"), "api_key=[REDACTED]")) }Call
addBeforeSendmultiple times to compose a chain – hooks are evaluated left-to-right (registration order). Returningnullfrom any hook short-circuits and drops the record. A hook that throws is treated the same as returningnull(the record is dropped, the exception is logged via the SDK's internal debug logger). Returning a record with a blank body also drops the record.addBeforeSendandremoveBeforeSendare live – added or removed hooks take effect on the nextcaptureLogcall.From Java, register a
PostHogBeforeSendLogSAM:config.getLogs().addBeforeSend(record -> record.getBody().contains("secret") ? null : record ); -
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 |