{"id":27627223,"url":"https://github.com/treasure-data/td-logger-java","last_synced_at":"2025-04-23T13:53:43.369Z","repository":{"id":1872734,"uuid":"2797978","full_name":"treasure-data/td-logger-java","owner":"treasure-data","description":"Treasure Data Logging Library for Java","archived":false,"fork":false,"pushed_at":"2023-07-12T17:55:07.000Z","size":700,"stargazers_count":12,"open_issues_count":3,"forks_count":10,"subscribers_count":81,"default_branch":"master","last_synced_at":"2024-04-10T19:38:20.221Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://docs.treasure-data.com/articles/java","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/treasure-data.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-11-17T19:30:28.000Z","updated_at":"2024-04-10T19:38:20.222Z","dependencies_parsed_at":"2022-08-26T01:23:44.672Z","dependency_job_id":null,"html_url":"https://github.com/treasure-data/td-logger-java","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-logger-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-logger-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-logger-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/treasure-data%2Ftd-logger-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/treasure-data","download_url":"https://codeload.github.com/treasure-data/td-logger-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250444244,"owners_count":21431612,"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":[],"created_at":"2025-04-23T13:53:42.641Z","updated_at":"2025-04-23T13:53:43.360Z","avatar_url":"https://github.com/treasure-data.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Treasure Data Logger for Java\n\n## Overview\n\nMany web/mobile applications generate huge amount of event logs (c,f. login,\nlogout, purchase, follow, etc).  Analyzing these event logs can be quite\nvaluable for improving services.  However, collecting these logs easily and\nreliably is a challenging task.\n\nTreasure Data Logger solves the problem by having: easy installation, small\nfootprint, plugins reliable buffering, log forwarding, etc.\n\n  * Treasure Data website: [http://treasuredata.com/](http://treasure-data.com/)\n  * Treasure Data GitHub: [https://github.com/treasure-data/](https://github.com/treasure-data/)\n\n**td-logger-java** is a Java library, to record events from Java application. It supports two modes of operation: direct and indirect upload (through a td-agent, learn more [here](http://help.treasuredata.com/customer/portal/topics/550539-installing-td-agent/articles)).\n\nThis library leverages the [Treasure Data Java Client library, **td-client-java**](https://github.com/treasure-data/td-client-java) in direct upload mode and the [Fluentd Java Logger library, **fluent-logger-java**](https://github.com/fluent/fluent-logger-java) in indirect upload mode.\n\n## Requirements\n\nJava \u003e= 1.6\n\n## Install\n\n### Install with all-in-one jar file\n\nYou can download all-in-one jar file for Treasure Data Logger.\n\n    $ wget http://central.maven.org/maven2/com/treasuredata/td-logger/${logger.version}/td-logger-${logger.version}-jar-with-dependencies.jar\n\nTo use Treasure Data Logger for Java, set the above jar file to your classpath.\n\n### Install from Maven repository\n\nTreasure Data Logger for Java is released on Treasure Data's Maven repository.\nYou can configure your pom.xml as follows to use it:\n\n    \u003cdependencies\u003e\n      ...\n      \u003cdependency\u003e\n        \u003cgroupId\u003ecom.treasuredata\u003c/groupId\u003e\n        \u003cartifactId\u003etd-logger\u003c/artifactId\u003e\n        \u003cversion\u003e${logger.version}\u003c/version\u003e\n      \u003c/dependency\u003e\n      ...\n    \u003c/dependencies\u003e\n\n    \u003crepositories\u003e\n      \u003crepository\u003e\n        \u003cid\u003ecentral.maven.org\u003c/id\u003e\n        \u003cname\u003etd-logger Maven Repository\u003c/name\u003e\n        \u003curl\u003ehttp://central.maven.org/maven2/\u003c/url\u003e\n      \u003c/repository\u003e\n    \u003c/repositories\u003e\n\n### Install with SBT (Build tool Scala)\n\nTo install td-logger From SBT (a build tool for Scala), please add the following lines to your build.sbt.\n\n    /* in build.sbt */\n    // Repositories\n    resolvers ++= Seq(\n      \"td-logger Maven Repository\" at \"http://central.maven.org/maven2/\"\n    )\n    // Dependencies\n    libraryDependencies ++= Seq(\n      \"com.treasure_data\" % \"td-logger\" % \"${logger.version}\"\n    )\n\n### Install from GitHub repository\n\nYou can get latest source code using git.\n\n    $ git clone https://github.com/treasure-data/td-logger-java.git\n    $ cd td-logger-java\n    $ mvn package\n\nYou will get the td-logger jar file in td-logger-java/target\ndirectory.  File name will be td-logger-${logger.version}-jar-with-dependencies.jar.\nFor more detail, see pom.xml.\n\n**Replace ${logger.version} with the current version of Treasure Data Logger for Java.**\n**The current version is 0.2.3.**\n\n## Configuration\n\nThis logging library provides a variety of configuration options as Java System properties.\nThese options can be specified on the command-line or using a properties file and loading it in the system properties at runtime.\n\n    Properties props = System.getProperties();\n    props.load(Main.class.getClassLoader().getResourceAsStream(\"treasure-data.properties\"));\n\nThe current list of supported properties and their significance follows.\n\n### Direct vs Indirect Upload\n\nTo select indirect upload through td-agent, please set the `td.logger.agentmode` property to 'true'.\nFor direct upload please set the property to 'false'.\n\nThe default value is `true`.\n\nAlso note that if the `TREASURE_DATA_API_KEY` environment variable is set, `td.logger.agentmode = false` will be set by default.\n\nIf you want to directly upload event logs from your application, you should set your own values to the following properties:\n\n    td.logger.agentmode=false\n    td.logger.api.key=\u003cyour API key\u003e\n\nYou also can configure api endpoint like following:\n\n    td.logger.agentmode=false\n    td.logger.api.key=\u003cyour API key\u003e\n    td.logger.api.server.scheme=https://\n    td.logger.api.server.host=api.treasuredata.com\n    td.logger.api.server.port=443\n\nOn the other hand if you want to upload data via td-agent, you should declare the following properties:\n\n    td.logger.agentmode=true\n    td.logger.agent.host=\u003cyour td-agent host\u003e\n    td.logger.agent.port=\u003cyour td-agent port\u003e\n\nSee below for the description of each of these properties.\n\n### Agent's Host and Port\n\nThese two propertie set the location and port the Treasure Agent can be reached by: `td.logger.agent.host` and `td.logger.agent.port`.\n\nTheir default value is `localhost` and `24224` respectively.\n\n### Agent's Tag Prefix\n\nTreasure Agent marks the logging events using a 'tag', which is formed by a series of alphanumeric strings separated by a period character: e.g. 'string1.string2.string3'. Events created this logger are tagged with the database and table name the events are expected to be imported to. On the receiving end, the Treasure Agent, the database and table name will be used to determine the final database and table destination in the Treasure Data Cloud.\n\nThe `td.logger.agent.tag` properties provide the ability to set a fixed prefix for the tag that will be automatically added to all events logged by the library. For example, if events are destined to the 'mydb' database, and 'mytable' table within it, setting the `td.logger.agent.tag` property to `mycomp` will cause the tag to become `mycomp.mydb.mytable` as opposed to the default `td.mydb.mytable`. This is very important as the tag matching on the Treasure Agent side will need to be `mycomp.*.*` as opposed to the standard `td.*.*`.\n\nThe default value is `td`.\n\n### Agent's Connection Timeout\n\nThe connection timeout can be set with the `td.logger.agent.timeout` property. The value is in seconds.\n\nThe default value is `3000` seconds.\n\n### Agent's Buffer Capacity\n\nThe agent's maximum buffering capacity can be set using the `td.logger.agent.buffercapacity` property. The value is in bytes.\n\nThe default value is `1048576` bytes (1 MB).\n\n### REST APIs Key\n\nIn order for the logger to be able to authenticate with your account in the Treasure Data Cloud, the REST APIs require an API key. The key can be provided by the `td.logger.api.key` property.\n\nThis property does not have a default value.\n\nAlternatively the API key can be provided via the `TREASURE_DATA_API_KEY` environment variable. The environment variable takes precedence over the `td.logger.api.key` property.\n\nPlease note that we recommend to use a write-only API key. To obtain one, please:\n\n1. Login into the Treasure Data Console at http://console.treasuredata.com;\n2. Visit your Profile page at http://console.treasuredata.com/users/current;\n3. Insert your password under the 'API Keys' panel;\n4. In the bottom part of the panel, under 'Write-Only API keys', either copy the API key or click on 'Generate New' and copy the new API key.\n\n### REST APIs Server Host and Port\n\nThe Treasure Data REST APIs Server host and port can be specified using the `td.logger.api.server.host`, `td.logger.api.server.port`, `td.logger.api.server.scheme` properties.\n\nTheir default values are `api.treasuredata.com` and `80` respectively.\n\nAlternatively the REST APIs Server can be specified with the `TD_API_SERVER` environment variable. The value of the environment variable is read by the 'td-client-java' library directly and takes precedence over all other properties for both 'td-logger-java' and 'td-client-java' (`td.api.server.host`, `td.api.server.port`, and `td.api.server.scheme`).\n\n### Auto Create\n\nBoth in case of Direct or Indirect Upload the system is able to create the destination table and/or database should they not already exist. This capability is disabled by default but can be enabled by setting the `td.logger.create.table.auto` to `true`.\n\nPlease note that depending on the permissions associated with the API key in use (either the one provided for direct upload or the one configured for the td-agent) databases may not be allowed to be created. Please see this [Access control documentation](http://docs.treasuredata.com/articles/access-control) page for more information.\n\n## Quickstart\n\n### Small example with Treasure Data Logger\n\nThe following program is a small example of td-logger.\n\n    import java.io.IOException;\n    import java.util.HashMap;\n    import java.util.Map;\n    import java.util.Properties;\n    import com.treasure_data.logger.TreasureDataLogger;\n\n    public class Main {\n        private static TreasureDataLogger LOG;\n\n        static {\n            try {\n                Properties props = System.getProperties();\n                props.load(Main.class.getClassLoader().getResourceAsStream(\"treasure-data.properties\"));\n                LOG = TreasureDataLogger.getLogger(\"my_database\");\n            } catch (IOException e) {\n                // do something\n            }\n        }\n\n        public void doApp() {\n            Map\u003cString, Object\u003e data = new HashMap\u003cString, Object\u003e();\n            data.put(\"from\", \"userA\");\n            data.put(\"to\", \"userB\");\n            LOG.log(\"my_follow_table\", data);\n        }\n    }\n\nSee static initializer in Main class.  To create TreasureDataLogger objects,\nyou need to invoke getLogger method in TreasureDataLogger class like\nwell-known logging libraries.  The method should be called only once.\n\nThe close method in the TreasureDataLogger class should be called explicitly\nwhen your application is finished (or unloaded). Once the method is executed,\nall TreasureDataLogger objects that you created are closed.\n\n    TreasureDataLogger.close();\n\nSee doApp method in the Main class. The log method enables you to upload event logs.\nEvent logs should be declared as variables of Map\\\u003cString, Object\\\u003e type.\nThe key is String type.  The type of value is one of the followings: int,\nlong, string, float, double.\n\n## License\n\nApache License, Version 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreasure-data%2Ftd-logger-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftreasure-data%2Ftd-logger-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreasure-data%2Ftd-logger-java/lists"}