Skip to content

Commit 0335bdf

Browse files
tanderson-ldtanderson-ld
authored
docs: adds Dokka Javadoc generation and integration into docs publish… (#215)
Leverages Dokka plugin and integrates into the existing docs publishing workflow via Makefile. I expect some small tweaks to get the upload into the Github pages to play nicely. <img width="1672" height="866" alt="image" src="https://github.com/user-attachments/assets/95f4b293-38b4-4923-b4b5-3dc14ad9582e" />
1 parent 806ce08 commit 0335bdf

File tree

12 files changed

+295
-4
lines changed

12 files changed

+295
-4
lines changed

‎e2e/android/app/build.gradle.kts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ android {
1212
defaultConfig {
1313
applicationId = "com.example.androidobservability"
1414
minSdk = 24
15-
targetSdk = 35
1615
versionCode = 1
1716
versionName = "1.0"
1817

‎sdk/@launchdarkly/observability-android/Makefile‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
.PHONY: install build test docs
2+
3+
install:
4+
@echo "Install target does nothing for this project"
5+
6+
build:
7+
./gradlew :lib:build
8+
9+
test:
10+
./gradlew :lib:test
11+
12+
docs:
13+
./gradlew :lib:dokkaJavadoc
14+
ln -sf lib/docs docs

‎sdk/@launchdarkly/observability-android/README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# LaunchDarkly Observability SDK for Android
2+
3+
## Early Access Preview️
4+
5+
**NB: APIs are subject to change until a 1.x version is released.**
6+
7+
## Features
8+
9+
### Automatic Instrumentation
10+
11+
The Android observability plugin automatically instruments:
12+
- **Activity Lifecycle**: App lifecycle events and transitions
13+
- **HTTP Requests**: OkHttp and HttpURLConnection requests (requires setup of ByteBuddy compile time plugin and additional dependencies)
14+
- **Crash Reporting**: Automatic crash reporting and stack traces
15+
- **Feature Flag Evaluations**: Evaluation events added to your spans.
16+
- **Session Management**: User session tracking and background timeout handling
17+
18+
## Example Application
19+
20+
A complete example application is available in the [e2e/android](../e2e/android) directory.
21+
22+
## Install
23+
24+
Add the dependency to your app's Gradle file:
25+
26+
```kotlin
27+
dependencies {
28+
implementation("com.launchdarkly:launchdarkly-android-client-sdk:5.+")
29+
implementation("com.launchdarkly:launchdarkly-observability-android:0.5.0")
30+
}
31+
```
32+
33+
## Usage
34+
35+
### Basic Setup
36+
37+
Add the observability plugin to your LaunchDarkly Android Client SDK configuration:
38+
39+
```kotlin
40+
import com.launchdarkly.observability.plugin.Observability
41+
import com.launchdarkly.sdk.android.LDConfig
42+
import com.launchdarkly.sdk.android.Components
43+
import com.launchdarkly.sdk.android.LDClient
44+
45+
class MyApplication : Application() {
46+
override fun onCreate() {
47+
super.onCreate()
48+
49+
val ldConfig = LDConfig.Builder(LDConfig.Builder.AutoEnvAttributes.Enabled)
50+
.mobileKey("your-mobile-key")
51+
.plugins(
52+
Components.plugins().setPlugins(
53+
listOf(
54+
Observability(this@MyApplication)
55+
)
56+
)
57+
)
58+
.build()
59+
60+
val context = LDContext.builder(ContextKind.DEFAULT, "user-key")
61+
.build()
62+
63+
LDClient.init(this@MyApplication, ldConfig, context)
64+
}
65+
}
66+
```
67+
68+
### Configure additional instrumentations
69+
70+
To enable HTTP request instrumentation and user interaction instrumentation, add the following plugin and dependencies to your top level application's Gradle file.
71+
72+
<CodeBlocks>
73+
<CodeBlock title='Gradle Groovy'>
74+
75+
```java
76+
plugins {
77+
id 'net.bytebuddy.byte-buddy-gradle-plugin' version '1.+'
78+
}
79+
80+
dependencies {
81+
// Android HTTP Url instrumentation
82+
implementation 'io.opentelemetry.android.instrumentation:httpurlconnection-library:0.11.0-alpha'
83+
byteBuddy 'io.opentelemetry.android.instrumentation:httpurlconnection-agent:0.11.0-alpha'
84+
85+
// OkHTTP instrumentation
86+
implementation 'io.opentelemetry.android.instrumentation:okhttp3-library:0.11.0-alpha'
87+
byteBuddy 'io.opentelemetry.android.instrumentation:okhttp3-agent:0.11.0-alpha'
88+
}
89+
```
90+
91+
### Advanced Configuration
92+
93+
You can customize the observability plugin with various options:
94+
95+
```kotlin
96+
import com.launchdarkly.observability.api.Options
97+
import com.launchdarkly.sdk.android.LDAndroidLogging
98+
import io.opentelemetry.api.common.AttributeKey
99+
import io.opentelemetry.api.common.Attributes
100+
101+
val observabilityPlugin = Observability(
102+
application = this@MyApplication,
103+
options = Options(
104+
serviceName = "my-android-app",
105+
serviceVersion = "1.0.0",
106+
debug = true,
107+
logAdapter = LDAndroidLogging.adapter(),
108+
resourceAttributes = Attributes.of(
109+
AttributeKey.stringKey("environment"), "production",
110+
AttributeKey.stringKey("team"), "mobile"
111+
),
112+
customHeaders = mapOf(
113+
"X-Custom-Header" to "custom-value"
114+
)
115+
)
116+
)
117+
```
118+
119+
### Recording Observability Data
120+
121+
After initialization of the LaunchDarkly Android Client SDK, use `LDObserve` to record metrics, logs, errors, and traces:
122+
123+
```kotlin
124+
import com.launchdarkly.observability.sdk.LDObserve
125+
import com.launchdarkly.observability.interfaces.Metric
126+
import io.opentelemetry.api.common.AttributeKey
127+
import io.opentelemetry.api.common.Attributes
128+
import io.opentelemetry.api.logs.Severity
129+
130+
// Record metrics
131+
LDObserve.recordMetric(Metric("user_actions", 1.0))
132+
LDObserve.recordCount(Metric("api_calls", 1.0))
133+
LDObserve.recordIncr(Metric("page_views", 1.0))
134+
LDObserve.recordHistogram(Metric("response_time", 150.0))
135+
LDObserve.recordUpDownCounter(Metric("active_connections", 1.0))
136+
137+
// Record logs
138+
LDObserve.recordLog(
139+
"User performed action",
140+
Severity.INFO,
141+
Attributes.of(
142+
AttributeKey.stringKey("user_id"), "12345",
143+
AttributeKey.stringKey("action"), "button_click"
144+
)
145+
)
146+
147+
// Record errors
148+
LDObserve.recordError(
149+
Exception("Something went wrong"),
150+
Attributes.of(
151+
AttributeKey.stringKey("component"), "payment",
152+
AttributeKey.stringKey("error_code"), "PAYMENT_FAILED"
153+
)
154+
)
155+
156+
// Create spans for tracing
157+
val span = LDObserve.startSpan(
158+
"api_request",
159+
Attributes.of(
160+
AttributeKey.stringKey("endpoint"), "/api/users",
161+
AttributeKey.stringKey("method"), "GET"
162+
)
163+
)
164+
span.makeCurrent().use {
165+
// Your code here
166+
}
167+
span.end()
168+
```
169+
170+
171+
172+
## Contributing
173+
174+
We encourage pull requests and other contributions from the community. Check out our [contributing guidelines](../../CONTRIBUTING.md) for instructions on how to contribute to this SDK.
175+
176+
## About LaunchDarkly
177+
178+
* LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
179+
* Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
180+
* Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
181+
* Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
182+
* Grant access to certain features based on user attributes, like payment plan (eg: users on the ‘gold’ plan get access to more features than users in the ‘silver’ plan). Disable parts of your application to facilitate maintenance, without taking everything offline.
183+
* LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Read [our documentation](https://docs.launchdarkly.com/sdk) for a complete list.
184+
* Explore LaunchDarkly
185+
* [launchdarkly.com](https://www.launchdarkly.com/ "LaunchDarkly Main Website") for more information
186+
* [docs.launchdarkly.com](https://docs.launchdarkly.com/ "LaunchDarkly Documentation") for our documentation and SDK reference guides
187+
* [apidocs.launchdarkly.com](https://apidocs.launchdarkly.com/ "LaunchDarkly API Documentation") for our API documentation
188+
* [launchdarkly.com/blog](https://launchdarkly.com/blog/ "LaunchDarkly Blog Documentation") for the latest product updates

‎sdk/@launchdarkly/observability-android/lib/build.gradle.kts‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
import java.net.URL
2+
13
plugins {
24
// Apply the Android library plugin
35
id("com.android.library")
@@ -6,6 +8,9 @@ plugins {
68

79
// Apply the Kotlin Android plugin for Android-compatible Kotlin support.
810
alias(libs.plugins.kotlin.android)
11+
12+
// Apply Dokka plugin for documentation generation
13+
id("org.jetbrains.dokka") version "2.0.0"
914
}
1015

1116
allprojects {
@@ -55,7 +60,7 @@ tasks.withType<Test> {
5560

5661
android {
5762
namespace = "com.launchdarkly.observability"
58-
compileSdk = 30
63+
compileSdk = 35
5964

6065
buildFeatures {
6166
buildConfig = true
@@ -96,6 +101,8 @@ publishing {
96101
artifactId = "launchdarkly-observability-android"
97102
version = releaseVersion
98103

104+
// artifact(dokkaJar)
105+
99106
pom {
100107
name.set("LaunchDarkly Observability Android SDK")
101108
description.set(
@@ -140,3 +147,16 @@ publishing {
140147
signing {
141148
sign(publishing.publications["release"])
142149
}
150+
151+
// Dokka configuration for Android library documentation
152+
tasks.dokkaJavadoc.configure {
153+
moduleName.set("launchdarkly-observability-android")
154+
moduleVersion.set(project.version.toString())
155+
outputDirectory.set(layout.projectDirectory.dir("docs"))
156+
157+
dokkaSourceSets {
158+
configureEach {
159+
includes.from("doc-module.md")
160+
}
161+
}
162+
}

‎sdk/@launchdarkly/observability-android/lib/doc-module.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Module launchdarkly-observability-android
2+
3+
This is the LaunchDarkly Observability package for Android. [Click here to view the README on our Github](https://github.com/launchdarkly/observability-sdk/tree/main/sdk/%40launchdarkly/observability-android/README.md)

‎sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/InstrumentationManager.kt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,11 @@ private const val INSTRUMENTATION_SCOPE_NAME = "com.launchdarkly.observability"
3939
/**
4040
* Manages instrumentation for LaunchDarkly Observability.
4141
*
42+
* @param application The application instance.
43+
* @param sdkKey The SDK key.
4244
* @param resources The OpenTelemetry resource describing this service.
45+
* @param logger The logger.
46+
* @param options Additional options.
4347
*/
4448
class InstrumentationManager(
4549
private val application: Application,

‎sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/client/ObservabilityClient.kt‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,19 @@ import io.opentelemetry.api.logs.Severity
1010
import io.opentelemetry.api.trace.Span
1111
import io.opentelemetry.sdk.resources.Resource
1212

13+
/**
14+
* The [ObservabilityClient] can be used for recording observability data such as
15+
* metrics, logs, errors, and traces.
16+
*
17+
* It is recommended to use the [Observability] plugin with the LaunchDarkly Android
18+
* Client SDK, as that will automatically initialize the [LDObserve] singleton instance.
19+
*
20+
* @param application The application instance.
21+
* @param sdkKey The SDK key.
22+
* @param resource The resource.
23+
* @param logger The logger.
24+
* @param options Additional options for the client.
25+
*/
1326
class ObservabilityClient: Observe {
1427
private val instrumentationManager: InstrumentationManager
1528

‎sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/interfaces/Metric.kt‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,14 @@ package com.launchdarkly.observability.interfaces
22

33
import io.opentelemetry.api.common.Attributes
44

5+
/**
6+
* A metric is a value that can be recorded in the LaunchDarkly observability system.
7+
*
8+
* @param name The name of the metric.
9+
* @param value The value of the metric.
10+
* @param attributes The attributes of the metric.
11+
* @param timestamp The timestamp of the metric.
12+
*/
513
data class Metric(
614
val name: String,
715
val value: Double,

‎sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/interfaces/Observe.kt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import io.opentelemetry.api.trace.Span
66

77
/**
88
* Interface for observability operations in the LaunchDarkly Android SDK.
9-
* Provides methods for recording various types of metrics.
9+
* Provides methods for recording various types of information.
1010
*/
1111
interface Observe {
1212
/**

‎sdk/@launchdarkly/observability-android/lib/src/main/kotlin/com/launchdarkly/observability/plugin/EvalTracingHook.kt‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,13 @@ import io.opentelemetry.api.trace.Span
1010
import io.opentelemetry.api.trace.Tracer
1111
import io.opentelemetry.context.Context
1212

13+
/**
14+
* This class is a hook implementation for recording flag evaluation events
15+
* on spans.
16+
*/
1317
class EvalTracingHook
1418
/**
15-
* Creates a [EvalTracingHook]
19+
* Creates an [EvalTracingHook]
1620
*
1721
* @param withSpans will include child spans for the various hook series when they happen
1822
* @param withValue will include the value of the feature flag in the recorded evaluation events

0 commit comments

Comments
 (0)