Skip to content

Commit 21c56b3

Browse files
Abhi347Abhi347
committed
doc: Add documentation
1 parent 65fadd7 commit 21c56b3

File tree

3 files changed

+130
-67
lines changed

3 files changed

+130
-67
lines changed

‎README.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
![lifecycle: beta](https://img.shields.io/badge/lifecycle-beta-509bf5.svg)
44
[![Maven Central](https://img.shields.io/maven-central/v/com.spotify/github-client)](https://mvnrepository.com/artifact/com.spotify/github-client)
55

6-
76
# github-java-client
87

98
A small Java library for talking to GitHub/GitHub Enterprise and interacting with projects.
@@ -74,6 +73,7 @@ log.info(repositoryClient.getCommit("sha").get().htmlUrl());
7473

7574
Another example of the mirrored structure is that some of the APIs are nested under a parent API.
7675
For example, endpoints related to check runs or issues are nested under the Repository client:
76+
7777
```java
7878
final ChecksClient checksClient = repositoryClient.createChecksApiClient();
7979
checksClient.createCheckRun(CHECK_RUN_REQUEST);
@@ -85,11 +85,51 @@ issueClient.createComment(ISSUE_ID, "comment body")
8585
```
8686

8787
And endpoints related to teams and memberships are nested under the Organisation client:
88+
8889
```java
8990
final TeamClient teamClient = organisationClient.createTeamClient();
9091
teamClient.getMembership("username");
9192
```
9293

94+
## Tracing
95+
96+
The GitHub client supports tracing via both OpenCensus and OpenTelemetry. Since OpenCensus is deprecated, we recommend
97+
using OpenTelemetry. Using OpenTelemetry also enables context propagation when using this library.
98+
To enable tracing, you need to provide a tracer when initializing the client.
99+
100+
### OpenTelemetry
101+
102+
```java
103+
import com.spotify.github.tracing.opentelemetry.OpenTelemetryTracer;
104+
105+
final GitHubClient githubClient =
106+
GitHubClient.create(baseUri, accessToken)
107+
// Uses GlobalOpenTelemetry.get() to fetch the default tracer
108+
.withTracer(new OpenTelemetryTracer());
109+
```
110+
111+
You can also provide a custom `OpenTelemetry` object if you want to use a specific one.
112+
113+
```java
114+
import com.spotify.github.tracing.opentelemetry.OpenTelemetryTracer;
115+
116+
final GitHubClient githubClient =
117+
GitHubClient.create(baseUri, accessToken)
118+
// Uses custom openTelemetry object to fetch the tracer
119+
.withTracer(new OpenTelemetryTracer(openTelemetry));
120+
```
121+
122+
### OpenCensus
123+
124+
```java
125+
import com.spotify.github.tracing.opencensus.OpenCensusTracer;
126+
127+
final GitHubClient githubClient =
128+
GitHubClient.create(baseUri, accessToken)
129+
// Uses Tracing.getTracer() to fetch the default tracer
130+
.withTracer(new OpenCensusTracer());
131+
```
132+
93133
## Supported Java versions
94134

95135
This library is written and published with Java version 11. In our CI workflows, we execute
@@ -107,6 +147,7 @@ mvn clean verify
107147
If you are a maintainer, you can release a new version by just triggering the workflow
108148
[prepare-release](./.github/workflows/prepare-release.yml) through the
109149
[web UI](https://github.com/spotify/github-java-client/actions/workflows/prepare-release.yml).
150+
110151
- Select whether the new release should be a `major`, `minor` or `patch` release
111152
- Trigger the release preparation on the `master` branch
112153
- Pushes of this workflow will trigger runs of the

‎src/main/java/com/spotify/github/tracing/opencensus/OpenCensusTracer.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
import okhttp3.*;
3434
import org.jetbrains.annotations.NotNull;
3535

36+
/** Tracer implementation using OpenCensus. */
3637
public class OpenCensusTracer extends BaseTracer {
3738

3839
private static final io.opencensus.trace.Tracer TRACER = Tracing.getTracer();

‎src/main/java/com/spotify/github/tracing/opentelemetry/OpenTelemetryTracer.java‎

Lines changed: 87 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -39,72 +39,93 @@
3939

4040
import static java.util.Objects.requireNonNull;
4141

42+
/** Tracer implementation using OpenTelemetry. */
4243
public class OpenTelemetryTracer extends BaseTracer {
43-
private final io.opentelemetry.api.trace.Tracer tracer;
44-
private final OpenTelemetry openTelemetry;
45-
46-
public OpenTelemetryTracer(final OpenTelemetry openTelemetry) {
47-
this.openTelemetry = openTelemetry;
48-
this.tracer = openTelemetry.getTracer("github-java-client");
49-
50-
}
51-
52-
public OpenTelemetryTracer() {
53-
this(GlobalOpenTelemetry.get());
54-
}
55-
56-
@SuppressWarnings("MustBeClosedChecker")
57-
protected Span internalSpan(
58-
final String path,
59-
final String method,
60-
final CompletionStage<?> future) {
61-
requireNonNull(path);
62-
63-
Context context = Context.current();
64-
65-
final io.opentelemetry.api.trace.Span otSpan =
66-
tracer.spanBuilder("GitHub Request")
67-
.setParent(context)
68-
.setSpanKind(SpanKind.CLIENT).startSpan();
69-
70-
otSpan.setAttribute("component", "github-api-client");
71-
otSpan.setAttribute("peer.service", "github");
72-
otSpan.setAttribute("http.url", path);
73-
otSpan.setAttribute("method", method);
74-
final Span span = new OpenTelemetrySpan(otSpan);
75-
76-
if (future == null) {
77-
return span;
78-
} else {
79-
attachSpanToFuture(span, future);
80-
}
81-
return span;
82-
}
83-
84-
@Override
85-
protected Span internalSpan(final Request request, final CompletionStage<?> future) {
86-
requireNonNull(request);
87-
Context context = W3CTraceContextPropagator.getInstance().extract(Context.current(), request, new TextMapGetter<>() {
88-
@Override
89-
public Iterable<String> keys(@NotNull final Request carrier) {
90-
return carrier.headers().names();
91-
}
92-
93-
@Nullable
94-
@Override
95-
public String get(@Nullable final Request carrier, @NotNull final String key) {
96-
if (carrier == null) {
97-
return null;
98-
}
99-
return carrier.header(key);
100-
}
101-
});
102-
context.makeCurrent();
103-
return internalSpan(request.url().toString(), request.method(), future);
104-
}
105-
106-
@Override
107-
public Call.Factory createTracedClient(final OkHttpClient client) {
108-
return OkHttpTelemetry.builder(openTelemetry).build().newCallFactory(client);
44+
private final io.opentelemetry.api.trace.Tracer tracer;
45+
private final OpenTelemetry openTelemetry;
46+
47+
public OpenTelemetryTracer(final OpenTelemetry openTelemetry) {
48+
this.openTelemetry = openTelemetry;
49+
this.tracer = openTelemetry.getTracer("github-java-client");
50+
}
51+
52+
public OpenTelemetryTracer() {
53+
this(GlobalOpenTelemetry.get());
54+
}
55+
56+
/**
57+
* Create a new span for the given path and method.
58+
*
59+
* @param path The path of the request.
60+
* @param method The method of the request.
61+
* @param future The future to attach the span to.
62+
* @return The created span.
63+
*/
64+
@SuppressWarnings("MustBeClosedChecker")
65+
protected Span internalSpan(
66+
final String path, final String method, final CompletionStage<?> future) {
67+
requireNonNull(path);
68+
69+
Context context = Context.current();
70+
71+
final io.opentelemetry.api.trace.Span otSpan =
72+
tracer
73+
.spanBuilder("GitHub Request")
74+
.setParent(context)
75+
.setSpanKind(SpanKind.CLIENT)
76+
.startSpan();
77+
78+
otSpan.setAttribute("component", "github-api-client");
79+
otSpan.setAttribute("peer.service", "github");
80+
otSpan.setAttribute("http.url", path);
81+
otSpan.setAttribute("method", method);
82+
final Span span = new OpenTelemetrySpan(otSpan);
83+
84+
if (future == null) {
85+
return span;
86+
} else {
87+
attachSpanToFuture(span, future);
10988
}
89+
return span;
90+
}
91+
92+
/**
93+
* Create a new span for the given request.
94+
*
95+
* @param request The request to create a span for.
96+
* @param future The future to attach the span to.
97+
* @return The created span.
98+
*/
99+
@Override
100+
protected Span internalSpan(final Request request, final CompletionStage<?> future) {
101+
requireNonNull(request);
102+
// Extract the context from the request headers.
103+
Context context =
104+
W3CTraceContextPropagator.getInstance()
105+
.extract(
106+
Context.current(),
107+
request,
108+
new TextMapGetter<>() {
109+
@Override
110+
public Iterable<String> keys(@NotNull final Request carrier) {
111+
return carrier.headers().names();
112+
}
113+
114+
@Nullable
115+
@Override
116+
public String get(@Nullable final Request carrier, @NotNull final String key) {
117+
if (carrier == null) {
118+
return null;
119+
}
120+
return carrier.header(key);
121+
}
122+
});
123+
context.makeCurrent();
124+
return internalSpan(request.url().toString(), request.method(), future);
125+
}
126+
127+
@Override
128+
public Call.Factory createTracedClient(final OkHttpClient client) {
129+
return OkHttpTelemetry.builder(openTelemetry).build().newCallFactory(client);
130+
}
110131
}

0 commit comments

Comments
 (0)