{"id":19653563,"url":"https://github.com/sematext/sematext-logsene-android","last_synced_at":"2025-04-28T17:31:38.646Z","repository":{"id":49165958,"uuid":"55164407","full_name":"sematext/sematext-logsene-android","owner":"sematext","description":"Sematext Logs Client Library for Android","archived":false,"fork":false,"pushed_at":"2024-06-24T15:57:57.000Z","size":1809,"stargazers_count":22,"open_issues_count":3,"forks_count":10,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-21T11:08:30.192Z","etag":null,"topics":["android","log-management","logging","logs","logshipper","mobile-analytics","monitoring"],"latest_commit_sha":null,"homepage":"https://sematext.com/logsene","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sematext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-31T16:06:20.000Z","updated_at":"2024-06-24T15:58:00.000Z","dependencies_parsed_at":"2022-09-05T19:21:21.885Z","dependency_job_id":null,"html_url":"https://github.com/sematext/sematext-logsene-android","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fsematext-logsene-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fsematext-logsene-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fsematext-logsene-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sematext%2Fsematext-logsene-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sematext","download_url":"https://codeload.github.com/sematext/sematext-logsene-android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251355432,"owners_count":21576358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","log-management","logging","logs","logshipper","mobile-analytics","monitoring"],"created_at":"2024-11-11T15:14:31.426Z","updated_at":"2025-04-28T17:31:38.267Z","avatar_url":"https://github.com/sematext.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[logsene]: https://sematext.com/logsene/\n[register]: https://apps.sematext.com/ui/registration\n[hosted-kibana]: https://sematext.com/docs/logs/kibana/\n[video-tutorials]: https://www.elastic.co/blog/kibana-4-video-tutorials-part-1\n\nSDK for Shipping Android Application Logs to Sematext\n==========================================================\n\n[![](https://jitpack.io/v/sematext/sematext-logsene-android.svg)](https://jitpack.io/#sematext/sematext-logsene-android)\n[![License](https://img.shields.io/github/license/sematext/sematext-logsene-android.svg)](https://img.shields.io/github/license/sematext/sematext-logsene-android.svg)\n\n[Sematext Logs is ELK as a Service][logsene]. This library lets you collect **mobile analytics** and **log data** from your Android applications using Sematext. There is an equivalent library for [shipping logs from iOS](https://github.com/sematext/sematext-logsene-ios) available.  If you don't have a Sematext account, you can [register for free][register] to get your [App](https://sematext.com/docs/guide/app-guide/) token.\n\nUse the **Mobile Application Logs** Integration to get out-of-the-box reports with the most important information about your mobile applications.\n\nGet an overview of your mobile apps with information like:\n - top Android versions\n - top log severities and version names\n\n![Mobile Logpack Overview](images/mobile_overview.png)\n\nExplore the common errors associated with your mobile applications and see an aggregated error view including:\n - number of errors and theirs count over time\n - top operating systems, top Android versions that are reporting errors\n - error log events\n\n![Mobile Logpack Errors](images/mobile_errors.png)\n\nGet insights from dedicated Android report that include:\n - mobile operating system logs count histogram and their count\n - top severities, versions, version codes, and version names\n - mobile applications log events\n\n![Mobile Logpack Android](images/mobile_android.png)\n\nGetting Started\n===============\n\nIf you haven't already, register for a free account. Create a new Logs App to get the App token, you will need it later.\n\nAdd the following gradle dependency to your Android application:\n\n```\nallprojects {\n repositories {\n    mavenCentral()\n    maven { url \"https://jitpack.io\" }\n }\n}\n\ndependencies {\n    compile 'com.github.sematext:sematext-logsene-android:3.2.0'\n}\n```\n\nThe library sends data to Sematext servers, so you will need to add the `INTERNET` and `ACCESS_NETWORK_STATE` permissions to your application manifest.\n\n```xml\n\u003cuses-permission android:name=\"android.permission.INTERNET\"\u003e\u003c/uses-permission\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_NETWORK_STATE\"\u003e\u003c/uses-permission\u003e\n```\n\nThe library sends data in batches to preserve battery (every 15 minutes), or if\nthere are more than 10 events queued up. Events are saved while the device is\noffline so you don't have to worry about losing any data. By default the\nlibrary keeps up to 5,000 events while offline.\n\nAdd the following inside the application manifest (inside `\u003capplication\u003e`):\n\n```xml\n \u003cmeta-data\n   android:name=\"LogseneAppToken\"\n   android:value=\"yourtoken\" /\u003e\n \u003cmeta-data\n   android:name=\"LogseneType\"\n   android:value=\"example\" /\u003e\n\n \u003c!-- For EU region use https://logsene-receiver.eu.sematext.com as the receiverUrl --\u003e\n \u003cmeta-data\n   android:name=\"LogseneReceiverUrl\"\n   android:value=\"https://logsene-receiver.sematext.com\" /\u003e\n```\n\n * **LogseneAppToken (required)**: This is your Logs App token, you should have received one after registering and creating your Logs App. We **highly recommend** creating a write-only token in your app settings to prevent any unauthorized access to your logs.\n * **LogseneType (required)**: Type to be used for all events (Sematext Logs uses Elasticsearch compatible API)\n * **LogseneMaxOfflineMessages**: Maximum number of offline stored events. Events are stored on the device while it's offline, or if the library is unable to send them to Sematext for some reason.\n * **LogseneReceiverUrl**: If you are using Sematext Cloud US region use https://logsene-receiver.sematext.com. For EU region use https://logsene-receiver.eu.sematext.com as the `receiverUrl`.\n * **LogseneMinTimeDelay**: Minimum amount of time (in milliseconds) to wait between sending logs while application is running and creating new log messages\n * **LogseneInterval**: time interval (in milliseconds) for sending logs regardless of app being active (minimum 15 minutes)\n * **LogseneRequiresUnmeteredNetwork**: if logs should be shipped only on unmetered network connection\n * **LogseneRequiresDeviceIdle**: if logs should be shipped only when device is idle\n * **LogseneRequiresBatteryNotLow**: if logs should be shipped only when battery is not low\n * **LogseneAutomaticLocationEnabled**: if logs should be automatically enriched with device location information. See the **Enriching Logs with Location** section for more details.\n\nExample Application\n-------------------\n\nTo see how some basic use cases are actually implemented, checkout the bundled `TestApp` android application. Make sure to set your own App token in the Android manifest.\n\n**Note** that it's highly recommended that you use one instance of Logsene at any time in your app.\n\nInitializing Logsene\n--------------------\n\nStarting with version **3.0.0** of the Android library `Logsene` needs to be initialized in a **static** way in order to be used. This allows usage in classes that don't have `Context` available. To do that, you need to call the following in your application code. Keep in mind this is only needed **once**:\n\n```java\nLogsene.init(this);\n```\n\nTo get the instance of the `Logsene` object that supports logging you need to call the `getInstance()` method, for example:\n\n```java\nLogsene logsene = Logsene.getInstance();\nlogsene.info(\"Hello World!\");\n```\n\nMobile Application Analytics\n----------------------------\n\nOnce you've setup the Logsene service, it's trivial to start sending custom events. For example, you may want to send an event every time a user starts an activity. In that case you could put the following inside the `onCreate()` method:\n\n```java\ntry {\n    JSONObject event = new JSONObject();\n    event.put(\"activity\", this.getClass().getSimpleName());\n    event.put(\"action\", \"started\");\n    Logsene logsene = Logsene.getInstance();\n    logsene.event(event);\n} catch (JSONException e) {\n    Log.e(\"myapp\", \"Unable to construct json\", e);\n}\n```\n\nTo visualize the collected data use [Sematext dashboards](https://sematext.com/docs/dashboards/).\n\nIf you don't see the events in the dashboard immediately, note that data are sent in batches to preserve the battery (every 60s), or if there are more than 10 events queued up. Events are saved while the device is offline, so you don't have to worry about losing any data.\n\nWhen it comes to the structure of your events, you are free to choose your own, the above is just an example. You can use any number of fields, and you can use nested fields. Basically, any valid JSON object will work fine. Note that the `meta` field is reserved for meta information (see [Meta Fields](#meta-fields) below). If you set a value for this field when sending an event, the meta information will not be included for that event.\n\nMeta Fields\n-----------\n\nMeta data are added to each event, all stored within the \"meta\" field:\n\n * versionName (as defined in your build.gradle)\n * versionCode (as defined in your build.gradle)\n * osRelease (android version)\n * uuid (unique identifier for this app installation)\n\nYou can set your own meta fields with `Logsene.setDefaultMeta()`. For example:\n\n```java\ntry {\n    JSONObject meta = new JSONObject();\n    meta.put(\"user\", \"user@example.com\");\n    Logsene.setDefaultMeta(meta);\n} catch (JSONException e) {\n    Log.e(\"myapp\", \"Unable to construct json\", e);\n}\n```\n\nNote that these meta fields are global, and will be attached to every event sent to Sematext.\n\nPausing \u0026 Resuming Logs Sending\n-------------------------------\n\nThe library can be instructed to stop sending logs on demand. To do that you need to call the following function:\n\n```java\nlogsene.pause();\n```\n\nLogs sending can be resumed by calling the following function:\n\n```java\nlogsene.resume();\n```\n\nNote that the logs that are in the buffer and were waiting to be sent at the time of pausing will not be sent until the logs sending process is resumed. \n\n\nCentralized Logging\n-------------------\n\nThe library offers some basic functions for centralized logging:\n\n- `Logsene.debug(String)`\n- `Logsene.info(String)`\n- `Logsene.warn(String)`\n- `Logsene.warn(Throwable)`\n- `Logsene.error(String)`\n- `Logsene.error(Throwable)`\n\nFor integrating with existing logging frameworks, see below.\n\nEnriching Logs with Location\n----------------------------\n\nLogs can be enriched with location data manually and automatically. For manual enriching the library supports the following methods:\n\n- `Logsene.debug(String, Double, Double)`\n- `Logsene.info(String, Double, Double)`\n- `Logsene.warn(String, Double, Double)`\n- `Logsene.warn(Throwable, Double, Double)`\n- `Logsene.error(String, Double, Double)`\n- `Logsene.error(Throwable, Double, Double)`\n\nFor example:\n\n```\nlogsene.info(\"Hello World with Location!\", 53.08, 23.08);\n```\n\nIt is also possible to tell the library to automatically retrieve location from the device. In such case the `Logsene` object instance needs to be created in the following way:\n\n```\nLogsene.init(this);\nLogsene logsene = Logsene.getInstance();\nlogsene.initializeLocationListener(context);\n```\n\nBecause of the automatic retrieval of location from the device the `ACCESS_COARSE_LOCATION` and `ACCESS_FINE_LOCATION` permissions are needed:\n\n```\n\u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"\u003e\u003c/uses-permission\u003e\n\u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"\u003e\u003c/uses-permission\u003e\n```\n\nIt is also crucial to call the `initializeLocationListener(Context context)` method of the `Logsene` object after the user gives the application the permission to use location data. Otherwise it will not work. Example on how that can be done is included in the `com.sematext.logseneandroid.MainActivity` class.\n\n### JUL\n\nIf your application uses JUL (java.util.logging) loggers, you can use the provided custom Handler for Logsene. You will need to configure it through code, since we need a reference to the `Context` object. If you configure your loggers to use the `LogseneHandler`, all log messages will be sent to Sematext for centralized logging.\n\n```java\nLogsene.init(this);\nLogsene logsene = Logsene.getInstance();\nLogger logger = Logger.getLogger(\"mylogger\");\nlogger.addHandler(new LogseneHandler(logsene));\n```\n\n### Using this SDK with Timber and Timber.Tree\n\nTimber is a logger with a small, extensible API which provides utility on top of Android's normal Log class.  To use Timber with this SDK for shipping Android logs to Sematext have a look at https://github.com/JakeWharton/timber/blob/master/timber-sample/src/main/java/com/example/timber/ExampleApp.java. You can extend `Timber.Tree` and overwrite the log method and include logging using the `Logsene` object there. Simply initialize the `Logsene` object in the `onCreate` method and everything should work from that point.\n\n### Logging exceptions\n\nIf you use JUL and the `LogseneHandler`, all logged exceptions will be sent to Sematext, no further configuration is needed. However, if you don't use JUL, the library provides a helper method to log exceptions:\n\n```java\nLogsene.init(this);\nLogsene logsene = Logsene.getInstance();\ntry {\n    trySomeOperation();\n} catch (IOException e) {\n    logsene.error(e);\n}\n```\n\n### How to log uncaught exceptions (crashes)\n\nYou can log any uncaught exceptions by defining your own uncaught exception handler. You will need to define a custom `Application` class for this to work. For example:\n\n```java\npublic class TestApplication extends Application {\n    private Thread.UncaughtExceptionHandler defaultExceptionHandler;\n    private Thread.UncaughtExceptionHandler exceptionHandler = new Thread.UncaughtExceptionHandler() {\n        @Override\n        public void uncaughtException(Thread thread, Throwable ex) {\n            // Send uncaught exception to Logsene.\n            Logsene.init(TestApplication.this);\n            Logsene logsene = Logsene.getInstance();\n            logsene.error(ex);\n\n            // Run the default android handler if one is set\n            if (defaultExceptionHandler != null) {\n                defaultExceptionHandler.uncaughtException(thread, ex);\n            }\n        }\n    };\n\n    public TestApplication() {\n        defaultExceptionHandler = Thread.getDefaultUncaughtExceptionHandler();\n        Thread.setDefaultUncaughtExceptionHandler(exceptionHandler);\n    }\n}\n```\n\nDon't forget to declare the custom application class in your manifest (with `android:name` on `application` element).\n\nMigrating to version 3.1 from previous versions\n-----------------------------------------------\n\nStarting from version **3.1.0** Logsene Android SDK is no longer displaying the prompt to enable location services and provide appropriate rights. It is now the responsibility of the application itself.\n\nMigrating to version 3.x from 2.x\n---------------------------------\n\nStarting from version **3.0.0** Logsene Android SDK contains backwards incompatible changes related to how it is initialized. You no longer need to create the `Logsene` object everytime you would like to use it for logging. You no longer create the `Logsene` object itself like this:\n\n```java\nLogsene logsene = new Logsene(context, true);\n```\n\nInstead you call the `init(Context)` method once and retrieve the instance of `Logsene` object later:\n\n```java\nLogsene.init(context);\nLogsene logsene = Logsene.getInstance();\n```\n\nYou also need to include the `LogseneAutomaticLocationEnabled` property in your manifest file to enable automatic log enrichment with location data:\n\n```xml\n\u003cmeta-data\n    android:name=\"LogseneAutomaticLocationEnabled\"\n    android:value=\"true\" /\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsematext%2Fsematext-logsene-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsematext%2Fsematext-logsene-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsematext%2Fsematext-logsene-android/lists"}