Skip to content

Commit 3190209

Browse files
author
Joseph
authored
Merge pull request #2 from epishie/releng
Setup maven publishing and docs
2 parents d7232b4 + e76e184 commit 3190209

14 files changed

+462
-42
lines changed

‎.github/workflows/publish-docs.yml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
on:
2+
push:
3+
branches: [master]
4+
jobs:
5+
publish:
6+
runs-on: ubuntu-latest
7+
steps:
8+
- uses: actions/checkout@v2
9+
- name: Set up JDK 11
10+
uses: actions/setup-java@v2
11+
with:
12+
distribution: 'adopt'
13+
java-version: '11'
14+
- name: Setup Python
15+
uses: actions/setup-python@v2
16+
with:
17+
python-version: '3.x'
18+
- name: Install dependencies
19+
run: |
20+
python3 -m pip install --upgrade pip
21+
python3 -m pip install mkdocs
22+
python3 -m pip install mkdocs-material
23+
- name: Generate Docs
24+
run: ./gradlew dokkaHtml
25+
- name: Build Docs
26+
run: mkdocs build
27+
- name: Publish Docs
28+
uses: peaceiris/actions-gh-pages@v3
29+
with:
30+
github_token: ${{ secrets.GITHUB_TOKEN }}
31+
publish_dir: ./site

‎.github/workflows/publish.yml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
on:
2+
release:
3+
types: [published]
4+
jobs:
5+
publish:
6+
runs-on: ubuntu-latest
7+
steps:
8+
- uses: actions/checkout@v2
9+
- name: Set up JDK 11
10+
uses: actions/setup-java@v2
11+
with:
12+
distribution: 'adopt'
13+
java-version: '11'
14+
- name: Build
15+
run: ./gradlew clean :puree:build
16+
- name: Publish to Maven
17+
run: ./gradlew :puree:publishAllPublicationsToMavenRepository
18+
env:
19+
OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
20+
OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
21+
SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
22+
SIGNING_PASSPHRASE: ${{ secrets.SIGNING_PASSPHRASE }}

‎.github/workflows/test.yml

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
on:
2+
pull_request:
3+
branches: [master]
4+
jobs:
5+
unit_test:
6+
runs-on: ubuntu-latest
7+
steps:
8+
- uses: actions/checkout@v2
9+
- name: Set up JDK 11
10+
uses: actions/setup-java@v2
11+
with:
12+
distribution: 'adopt'
13+
java-version: '11'
14+
- name: Build
15+
run: ./gradlew clean build
16+
- name: Unit Test
17+
run: ./gradlew test
18+
android_test:
19+
runs-on: macos-latest
20+
steps:
21+
- uses: actions/checkout@v2
22+
- name: Set up JDK 11
23+
uses: actions/setup-java@v2
24+
with:
25+
distribution: 'adopt'
26+
java-version: '11'
27+
- name: Build
28+
run: ./gradlew clean build
29+
- name: Android Test
30+
uses: reactivecircus/android-emulator-runner@v2
31+
with:
32+
api-level: 29
33+
script: ./gradlew connectedCheck

‎LICENSE

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
Copyright (c) 2021 Cookpad Inc.
2+
3+
Permission is hereby granted, free of charge, to any person obtaining a copy
4+
of this software and associated documentation files (the "Software"), to deal
5+
in the Software without restriction, including without limitation the rights
6+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7+
copies of the Software, and to permit persons to whom the Software is
8+
furnished to do so, subject to the following conditions:
9+
10+
The above copyright notice and this permission notice shall be included in all
11+
copies or substantial portions of the Software.
12+
13+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
14+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
15+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
16+
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
17+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
18+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
19+
OR OTHER DEALINGS IN THE SOFTWARE.

‎build.gradle

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
// Top-level build file where you can add configuration options common to all sub-projects/modules.
22
buildscript {
3-
ext.kotlin_version = "1.5.0"
3+
apply from: 'gradle/versions.gradle'
4+
45
repositories {
56
google()
67
mavenCentral()
78
}
89
dependencies {
9-
classpath "com.android.tools.build:gradle:4.2.0"
10-
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
10+
classpath "com.android.tools.build:gradle:4.2.1"
11+
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$libVersions.kotlin"
1112

1213
// NOTE: Do not place your application dependencies here; they belong
1314
// in the individual module build.gradle files

‎demo/build.gradle

+5-11
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,18 @@
11
plugins {
22
id 'com.android.application'
33
id 'kotlin-android'
4-
id 'org.jetbrains.kotlin.plugin.serialization' version "$kotlin_version"
4+
id 'org.jetbrains.kotlin.plugin.serialization' version "$kotlinVersion"
55
}
66

77
android {
88
compileSdkVersion 30
9-
buildToolsVersion "30.0.3"
109

1110
defaultConfig {
1211
applicationId "com.cookpad.puree.kotlin.demo"
1312
minSdkVersion 21
1413
targetSdkVersion 30
1514
versionCode 1
1615
versionName "1.0"
17-
18-
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
1916
}
2017

2118
buildTypes {
@@ -43,13 +40,10 @@ android {
4340
dependencies {
4441
implementation project(":puree")
4542

46-
implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
47-
implementation 'androidx.core:core-ktx:1.3.2'
48-
implementation 'androidx.appcompat:appcompat:1.2.0'
43+
implementation "org.jetbrains.kotlin:kotlin-stdlib:$libVersions.kotlin"
44+
implementation 'androidx.core:core-ktx:1.5.0'
45+
implementation 'androidx.appcompat:appcompat:1.3.0'
4946
implementation 'com.google.android.material:material:1.3.0'
5047
implementation 'org.jetbrains.kotlinx:kotlinx-serialization-json:1.2.0'
51-
coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:1.1.5'
52-
testImplementation 'junit:junit:4.+'
53-
androidTestImplementation 'androidx.test.ext:junit:1.1.2'
54-
androidTestImplementation 'androidx.test.espresso:espresso-core:3.3.0'
48+
coreLibraryDesugaring "com.android.tools:desugar_jdk_libs:$libVersions.desugar"
5549
}

‎docs/README.md

+178-1
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,181 @@ Puree is a log collector which provides the following features:
99
- Batching: Send multiple logs in a single request.
1010
- Retrying: Retry to send logs after backoff time if sending logs fails.
1111

12-
[Documentation](https://ghe.ckpd.co/pages/joseph-iturralde/puree-kotlin/api/)
12+
![](./assets/overview.png)
13+
14+
Puree helps you unify your logging infrastructure.
15+
16+
[API Documentation](https://cookpad.github.io/puree-kotlin/api/)
17+
18+
# Installation
19+
20+
Gradle:
21+
22+
```gradle
23+
repositories {
24+
mavenCentral()
25+
}
26+
27+
dependencies {
28+
implementation("com.cookpad.puree-kotlin:puree-kotlin:$version")
29+
}
30+
31+
```
32+
33+
# Usage
34+
35+
## Initialization
36+
37+
Logs are posted through a `PureeLogger` instance which should be configured with the filters, outputs, store to be used and the log types to be supported, in `Application#onCreate()`.
38+
39+
```kotlin
40+
class MyApplication : Application() {
41+
lateinit var logger: PureeLogger
42+
43+
override fun onCreate() {
44+
logger = PureeLogger.Builder(
45+
lifecycle = ProcessLifeycleOwner.get().lifecycle,
46+
logSerializer = MyLogSerializer(),
47+
logStore = DbPureeLogStore(this, "my_puree.db")
48+
)
49+
.filter(
50+
MyFilter(),
51+
MyLog::class.java
52+
)
53+
.output(
54+
MyOutput(),
55+
MyLog::class.java
56+
)
57+
.build()
58+
}
59+
}
60+
```
61+
62+
## Log objects and serialization
63+
64+
Log objects must implement the `PureeLog` interface.
65+
66+
```kotlin
67+
data class MyLog(val eventName: String) : PureeLog
68+
```
69+
70+
Internally, Puree operates on log objects as JSON objects. Puree requires clients to implement a `PureeLogSerializer` that serializes the logs to JSON.
71+
72+
Sample serializer using kotlinx.serialization
73+
74+
```kotlin
75+
class MyLogSerializer : PureeLogSerializer {
76+
override fun serialize(log: PureeLog): JSONObject {
77+
val json = Json.encodeToString(log)
78+
return JSONObject(json)
79+
}
80+
}
81+
```
82+
83+
## Filters
84+
85+
`PureeFilter` can be registered to add common fields to specific logs.
86+
87+
```kotlin
88+
class AddTimeFilter : PureeFilter {
89+
override fun applyFilter(log: JSONObject): JSONObject {
90+
return log.apply {
91+
put("event_time", System.currentTimeMillis())
92+
}
93+
}
94+
}
95+
```
96+
97+
`PureeFilter` can also be used to skip logs by returning `null`
98+
99+
```kotlin
100+
class SamplingFilter(private val samplingRate: Float) : PureeFilter {
101+
override fun applyFilter(log: JSONObject): JSONObject? {
102+
return log.takeUnless { samplingRate < Random.nextFloat() }
103+
}
104+
}
105+
```
106+
107+
## Outputs
108+
109+
There are two types of outputs: non-buffered and buffered.
110+
111+
`PureeOutput`: Non-buffered output. Writes logs immediately.
112+
`PureeBufferedOutput`: Buffered output. Enqueues logs to a local store and then flush them in the background.
113+
114+
For non-buffered outputs, implement a `PureeOutput`
115+
116+
```kotlin
117+
class LogcatOutput : PureeOutput {
118+
override fun emit(log: JSONObject) {
119+
Log.d("Puree", log.toString())
120+
}
121+
}
122+
```
123+
124+
For buffered ouptuts, extend `PureeBufferedOutput`. Buffered outputs can be configured by overriding its settings.
125+
126+
```kotlin
127+
class ServerLogBufferedOutput(private val logServerApi: LogServerApi) : PureeBufferedOutput("server_log_buffered") {
128+
override val flushInterval: Duration = Duration.ofMinutes(5) // Flush frequency
129+
override val logsPerFlush: Int = 1000 // Maximum number of logs in a batch.
130+
override val maxRetryCount: Int = 5 // Number of times a flush can be retried on failure
131+
override val exponentialBackoffBase: Duration = Duration.ofSeconds(2) // Base wait duration when retrying a failed flush
132+
override val purgeableAge: Duration? = Duration.ofDays(30) // How long the buffered logs are kept before purging
133+
override val maxFlushSizeInBytes: Long = Long.MAX_VALUE // The maximum size in bytes of the whole payload
134+
135+
override fun emit(logs: List<JSONObject>, onSuccess: () -> Unit, onFailed: (Throwable) -> Unit) {
136+
logServerApi.send(logs) { isSuccessful ->
137+
if (isSuccessful) {
138+
onSuccess()
139+
} else {
140+
onFailed(IOException("Error"))
141+
}
142+
}
143+
}
144+
}
145+
```
146+
147+
## Posting logs
148+
149+
Send logs using the `PureeLogger` instance:
150+
151+
```kotlin
152+
val pureeLogger = PureeLogger.Builder()
153+
// Configure the logger
154+
.build()
155+
156+
pureeLogger.postLog(MyLog())
157+
```
158+
159+
## Release engineering
160+
161+
* Update publication version in `gradle/publishing.gradle`
162+
* Create a Release in Github
163+
* Add release notes
164+
* Publish release
165+
166+
## License
167+
168+
```
169+
Copyright (c) 2021 Cookpad Inc.
170+
171+
Permission is hereby granted, free of charge, to any person obtaining a copy
172+
of this software and associated documentation files (the "Software"), to deal
173+
in the Software without restriction, including without limitation the rights
174+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
175+
copies of the Software, and to permit persons to whom the Software is
176+
furnished to do so, subject to the following conditions:
177+
178+
The above copyright notice and this permission notice shall be included in all
179+
copies or substantial portions of the Software.
180+
181+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
182+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
183+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
184+
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
185+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
186+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
187+
OR OTHER DEALINGS IN THE SOFTWARE.
188+
189+
```

‎docs/assets/logo-styles.css

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
#logo {
2+
background-image: url('../images/logo.png');
3+
background-size: 140px 50px;
4+
}

‎docs/assets/logo.png

45 KB
Loading

‎docs/assets/overview.png

146 KB
Loading

0 commit comments

Comments
 (0)