blob: 0298042e451d137cc4c9dd814ea0a652d328ea25 [file] [log] [blame]
Matthias Andreas Benkard80909242022-02-03 20:47:47 +01001// SPDX-FileCopyrightText: © 2021 Matthias Andreas Benkard <code@mail.matthias.benkard.de>
2//
3// SPDX-License-Identifier: LGPL-3.0-or-later
4
Matthias Andreas Benkard692f48d2021-08-31 21:06:50 +02005package eu.mulk.quarkus.googlecloud.jsonlogging;
6
7import java.util.Collection;
8
9/**
10 * A user-supplied provider for {@link Label}s.
11 *
Matthias Andreas Benkard20210242022-01-15 10:39:30 +010012 * <p>Instances of this interface that are registered with the {@link Formatter} are applied to each
13 * log entry that is logged.
14 *
15 * <p>If you are using the Quarkus extension, any CDI beans registered under this interface are
16 * registered automatically.
Matthias Andreas Benkard692f48d2021-08-31 21:06:50 +020017 *
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020018 * <p><strong>Example:</strong>
19 *
Matthias Andreas Benkarde369c512022-04-15 20:54:52 +020020 * {@snippet :
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020021 * @Singleton
22 * @Unremovable
23 * public final class RequestIdLabelProvider implements LabelProvider {
24 *
25 * @Override
26 * public Collection<Label> getLabels() {
27 * return List.of(Label.of("requestId", RequestContext.current().getRequestId()));
28 * }
29 * }
Matthias Andreas Benkarde369c512022-04-15 20:54:52 +020030 * }
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020031 *
Matthias Andreas Benkarde369c512022-04-15 20:54:52 +020032 * <p>Result:
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020033 *
Matthias Andreas Benkarde369c512022-04-15 20:54:52 +020034 * {@snippet lang="json" :
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020035 * {
36 * "textPayload": "Request rejected: unauthorized.",
37 * "labels": {
38 * "requestId": "123"
39 * }
40 * }
Matthias Andreas Benkarde369c512022-04-15 20:54:52 +020041 * }
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020042 *
Matthias Andreas Benkard692f48d2021-08-31 21:06:50 +020043 * @see StructuredParameterProvider
44 */
45public interface LabelProvider {
46
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020047 /**
48 * Provides a collection of {@link Label}s to add to each log entry that is logged.
49 *
Matthias Andreas Benkard2cc18b32022-09-03 10:03:30 +020050 * <p>If {@link #getLabels(Context)} is implemented, this method is ignored.
51 *
52 * @return a collection of {@link Label}s to add to each log entry that is logged.
53 * @see #getLabels(Context)
54 */
55 default Collection<Label> getLabels() {
56 return null;
57 }
58
59 /**
60 * Provides a collection of {@link Label}s to add to each log entry that is logged.
61 *
62 * <p>Delegates to {@link #getLabels()} by default.
63 *
Matthias Andreas Benkard42da9f12021-09-02 18:47:28 +020064 * @return a collection of {@link Label}s to add to each log entry that is logged.
65 */
Matthias Andreas Benkard2cc18b32022-09-03 10:03:30 +020066 default Collection<Label> getLabels(Context context) {
67 return getLabels();
68 }
69
70 /** Contextual data available to {@link #getLabels(Context)}. */
71 interface Context extends ProviderContext {}
Matthias Andreas Benkard692f48d2021-08-31 21:06:50 +020072}