blob: 79407cf846c2b0e97bd485148e07f1975892554e [file] [log] [blame]
Matthias Andreas Benkard37e804b2021-09-04 22:38:08 +02001= Quarkus Google Cloud JSON Logging
2Matthias Andreas Benkard
3// Meta
4:experimental:
5:data-uri:
6:sectnums:
7:toc:
8:stem:
9:toclevels: 2
10:description: Quarkus Google Cloud JSON Logging Manual
11:keywords: mulk
12// Settings
13:icons: font
14:source-highlighter: rouge
15
16
17Structured logging to standard output according to the Google Cloud
18Logging specification.
19
20
21== Summary
22
23This package contains a log formatter for JBoss Logging in the form of
24a Quarkus plugin that implements the
25https://cloud.google.com/logging/docs/structured-logging[Google Cloud
26Logging JSON format] on standard output.
27
28It is possible to log unstructured text, structured data, or a mixture
29of both depending on the situation.
30
31
Matthias Andreas Benkard37e804b2021-09-04 22:38:08 +020032== Activation
33
34Add the runtime POM to your dependency list. As long as the JAR is on
35the classpath at both build time and runtime, the log formatter
36automatically registers itself on startup.
37
38
39=== Activation with Maven
40
41[source,xml]
42----
43<project>
44 ...
45
46 <dependencies>
47 ...
48
49 <dependency>
50 <groupId>eu.mulk.quarkus-googlecloud-jsonlogging</groupId>
51 <artifactId>quarkus-googlecloud-jsonlogging</artifactId>
Matthias Andreas Benkard20210242022-01-15 10:39:30 +010052 <version>4.0.0</version>
Matthias Andreas Benkard37e804b2021-09-04 22:38:08 +020053 </dependency>
54
55 ...
56 </dependencies>
57
58 ...
59</project>
60----
61
62
63=== Activation with Gradle
64
65[source,groovy]
66----
67dependencies {
68 ...
69
Matthias Andreas Benkard20210242022-01-15 10:39:30 +010070 implementation("eu.mulk.quarkus-googlecloud-jsonlogging:quarkus-googlecloud-jsonlogging:4.0.0")
Matthias Andreas Benkard37e804b2021-09-04 22:38:08 +020071
72 ...
73}
74----
75
76
77== Usage
78
79Logging unstructured data requires no code changes. All logs are
80automatically converted to Google-Cloud-Logging-compatible JSON.
81
82Structured data can be logged in one of 3 different ways: by passing
83https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/Label.html[Label]s
84and
85https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameter.html[StructuredParameter]s
86as parameters to individual log entries, by supplying
87https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.html[LabelProvider]s
88and
89https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.html[StructuredParameterProvider]s,
90or by using the Mapped Diagnostic Context.
91
92
93=== Using Label and StructuredParameter
94
95Instances of
96https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/Label.html[Label]
97and
98https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameter.html[StructuredParameter]
99can be passed as log parameters to the `*f` family of logging
100functions on JBoss Logging's
101https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/Logger.html[Logger].
102
103Simple key–value pairs are represented by
104https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/KeyValueParameter.html[KeyValueParameter].
105
106**Example:**
107
108[source,java]
109----
110logger.logf(
111 "Request rejected: unauthorized.",
112 Label.of("requestId", "123"),
113 KeyValueParameter.of("resource", "/users/mulk"),
114 KeyValueParameter.of("method", "PATCH"),
115 KeyValueParameter.of("reason", "invalid token"));
116----
117
118Result:
119
120[source,json]
121----
122{
123 "jsonPayload": {
124 "message": "Request rejected: unauthorized.",
125 "resource": "/users/mulk",
126 "method": "PATCH",
127 "reason": "invalid token"
128 },
129 "labels": {
130 "requestId": "123"
131 }
132}
133----
134
135
136=== Using LabelProvider and StructuredParameterProvider
137
138Any CDI beans that implement
139https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/LabelProvider.html[LabelProvider]
140and
141https://javadocs.dev/eu.mulk.quarkus-googlecloud-jsonlogging/quarkus-googlecloud-jsonlogging/3.1.0/eu.mulk.quarkus.googlecloud.jsonlogging/eu/mulk/quarkus/googlecloud/jsonlogging/StructuredParameterProvider.html[StructuredParameterProvider]
142are discovered at build time and consulted to provide labels and
143parameters for each message that is logged. This can be used to
144provide contextual information such as tracing and request IDs stored
145in thread-local storage.
146
147**Example:**
148
149[source,java]
150----
151@Singleton
152@Unremovable
153public final class TraceLogParameterProvider implements StructuredParameterProvider, LabelProvider {
154
155 @Override
156 public StructuredParameter getParameter() {
157 var b = Json.createObjectBuilder();
158 b.add("traceId", Span.current().getSpanContext().getTraceId());
159 b.add("spanId", Span.current().getSpanContext().getSpanId());
160 return () -> b;
161 }
162
163 @Override
164 public Collection<Label> getLabels() {
165 return List.of(Label.of("requestId", "123"));
166 }
167}
168----
169
170Result:
171
172[source,json]
173----
174{
175 "jsonPayload": {
176 "message": "Request rejected: unauthorized.",
177 "traceId": "39f9a49a9567a8bd7087b708f8932550",
178 "spanId": "c7431b14630b633d"
179 },
180 "labels": {
181 "requestId": "123"
182 }
183}
184----
185
186
187=== Using the Mapped Diagnostic Context
188
189Any key–value pairs in JBoss Logging's thread-local
190https://docs.jboss.org/jbosslogging/latest/org/jboss/logging/MDC.html[MDC]
191are added to the resulting JSON.
192
193**Example:**
194
195[source,java]
196----
197MDC.put("resource", "/users/mulk");
198MDC.put("method", "PATCH");
199logger.logf("Request rejected: unauthorized.");
200----
201
202Result:
203
204[source,json]
205----
206{
207 "jsonPayload": {
208 "message": "Request rejected: unauthorized.",
209 "resource": "/users/mulk",
210 "method": "PATCH"
211 }
212}
213----