You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add references to the `cloud-logging`exporter to the documentation.
Describe the new config properties to control the extension.
Signed-off-by: Karsten Schnitter <[email protected]>
See the [example manifest](../sample-spring-boot/manifest-otel-javaagent.yml), how this translates into a deployment description.
39
40
40
-
For the instrumentation to send observability data to SAP Cloud Logging, the application needs to be bound to a corresponding service instance.
41
-
The service instance can be either managed or [user-provided](#using-user-provided-service-instances).
41
+
Once the agent is attached to the JVM with the ectension in place, there are two ways, which can be used to send data to [SAP Cloud Logging](https://discovery-center.cloud.sap/serviceCatalog/cloud-logging):
42
+
43
+
1. Use the `cloud-logging` exporters explicitly as provided by the extension.
44
+
This can be achieved via system properties or environment variables:
45
+
```sh
46
+
-Dotel.logs.exporter=cloud-logging \
47
+
-Dotel.metrics.exporter=cloud-logging \
48
+
-Dotel.traces.exporter=cloud-logging
49
+
50
+
#or
51
+
52
+
export OTEL_LOGS_EXPORTER=cloud-logging
53
+
export OTEL_METRICS_EXPORTER=cloud-logging
54
+
export OTEL_TRACES_EXPORTER=cloud-logging
55
+
java #...
56
+
```
57
+
58
+
2. Use the default `otlp` exporter with the provided default configuration from the extension:
59
+
60
+
```sh
61
+
-Dotel.logs.exporter=otlp \
62
+
-Dotel.metrics.exporter=otlp # default value \
63
+
-Dotel.traces.exporter=otlp # default value
64
+
65
+
#or
42
66
43
-
Note, that the OpenTelemetry Java Agent currently only sends traces and metrics by default.
44
-
To enable logs, the additional property `-Dotel.logs.exporter=otlp` is required.
67
+
export OTEL_LOGS_EXPORTER=otlp
68
+
export OTEL_METRICS_EXPORTER=otlp # default value
69
+
export OTEL_TRACES_EXPORTER=otlp # default value
70
+
java #...
71
+
```
72
+
73
+
Note, that the OpenTelemetry Java Agent currently sends traces and metrics by default using the `otlp` exporter.
74
+
That means, without any configuration the agent with the extension will forward metrics and traces to [SAP Cloud Logging](https://discovery-center.cloud.sap/serviceCatalog/cloud-logging).
75
+
See TODO for the difference between `cloud-logging` and `otlp` exporters.
76
+
The benefit of the `cloud-logging` exporter is, that it can be combined with a different configuration of the `otlp` exporter.
77
+
78
+
For the instrumentation to send observability data to [SAP Cloud Logging](https://discovery-center.cloud.sap/serviceCatalog/cloud-logging), the application needs to be bound to a corresponding service instance.
79
+
The service instance can be either managed or [user-provided](#using-user-provided-service-instances).
45
80
46
81
## Configuration
47
82
48
83
The OpenTelemetry Java Agent supports a wide variety of [configuration options](https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/).
49
84
As the extension provides configuration via SPI, all its configuration takes lower precedence than other configuration options for OpenTelemetry.
50
85
Users can easily overwrite any setting using environment variables or system properties.
51
86
87
+
### Using the Extension
88
+
89
+
The extension needs to be started with the OpenTelemetry Java Agent as outlined in the [Quick Start Guide](#quickstart-guide).
90
+
You need to enable shipping data either by using the `cloud-logging` exporters or relying on the `otlp` exporters for each signal type.
91
+
Multiple different exporters can be configured with comma separation.
92
+
Using the custom `cloud-logging` exporter will enable you, to use the default `otlp` exporter for different services.
93
+
The extension will configure a default endpoint and credentials for the `otlp` endpoints, so no further configuration is required.
94
+
95
+
Note, that the `cloud-logging` exporter is just a facade for the `otlp` exporter to allow configuration of multiple data sinks.
96
+
There is no custom network client provided by this extension.
97
+
52
98
### Configuring the Extension
53
99
54
100
The extension itself can be configured by specifying the following system properties:
55
101
56
102
| Property | Default Value | Comment |
57
103
|----------|---------------|---------|
58
-
|`com.sap.otel.extension.cloud-logging.label`|`cloud-logging`| The label of the managed service binding to bind to. |
59
-
|`com.sap.otel.extension.cloud-logging.tag`|`Cloud Logging`| The tag of any service binding (managed or user-provided) to bind to. |
60
-
|`otel.javaagent.extension.sap.cf.resource.enabled` or `env(OTEL_JAVAAGENT_EXTENSION_SAP_CF_RESOURCE_ENABLED)`|`true`| Whether to add CF resource attributes to all events. |
104
+
|`otel.javaagent.extension.sap.cf.binding.cloud-logging.label` or `com.sap.otel.extension.cloud-logging.label`|`cloud-logging`| The label of the managed service binding to bind to. |
105
+
|`otel.javaagent.extension.sap.cf.binding.cloud-logging.tag` or `com.sap.otel.extension.cloud-logging.tag`|`Cloud Logging`| The tag of any service binding (managed or user-provided) to bind to. |
106
+
|`otel.javaagent.extension.sap.cf.binding.user-provided.label`|`user-provided`| The label of a user-provided service binding to bind to. Note, this label is defined by the Cloud Foundry instance. |
107
+
|`otel.javaagent.extension.sap.cf.resource.enabled`|`true`| Whether to add CF resource attributes to all events. |
108
+
109
+
> The `otel.javaagent.extension.sap.*` properties are preferred over the `com.sap.otel.extension.*` properties, which are kept for compatibility.
110
+
Each `otel.javaagent.extension.sap.*` property can also be provided as environment variable `OTEL_JAVAAGENT_EXTENSION_SAP_*`.
61
111
62
112
The extension will scan the environment variable `VCAP_SERVICES` for CF service bindings.
63
113
User-provided bindings will take precedence over managed bindings of the configured label ("cloud-logging" by default).
@@ -90,7 +140,7 @@ The [OpenTelemetry Java Instrumentation project](https://github.com/open-telemet
90
140
91
141
## Using User-Provided Service Instances
92
142
93
-
The extension provides support not only for managed service instance of SAP Cloud Logging but also for user-provided service instances.
143
+
The extension provides support not only for managed service instance of [SAP Cloud Logging](https://discovery-center.cloud.sap/serviceCatalog/cloud-logging) but also for user-provided service instances.
94
144
This helps to fine-tune the configuration, e.g. leave out or reconfigure the syslog drain.
95
145
Furthermore, this helps on sharing service instances across CF orgs or landscapes.
96
146
@@ -103,7 +153,7 @@ The extension requires four fields in the user-provided service credentials and
103
153
|`ingest-otlp-cert`| The mTLS client certificate in PEM format matching the client key. Line breaks as `\n`. |
104
154
|`server-ca`| The trusted mTLS server certificate in PEM format. Line breaks as `\n`. |
105
155
106
-
If you have a SAP Cloud Logging service key, you can generate the required JSON file with jq:
156
+
If you have a [SAP Cloud Logging](https://discovery-center.cloud.sap/serviceCatalog/cloud-logging) service key, you can generate the required JSON file with jq:
107
157
108
158
```bash
109
159
cf service-key cls test \
@@ -119,5 +169,17 @@ Using this file, you can create the required user-provided service:
119
169
```
120
170
121
171
Note, that you can easily feed arbitrary credentials to the extension.
122
-
It does not need to be SAP Cloud Logging.
172
+
It does not need to be [SAP Cloud Logging](https://discovery-center.cloud.sap/serviceCatalog/cloud-logging).
123
173
You can even change the tag using the configuration parameters of the extension.
174
+
175
+
## Implementation Differences between Cloud-Logging and OTLP Exporter
176
+
177
+
The `cloud-logging` exporter provided by this extension is a facade for the `OtlpGrpcExporter` provided by the OpenTelemetry Java Agent, just like the `otlp` exporter.
178
+
The difference is just during the bootstrapping phase.
179
+
The main differences are:
180
+
181
+
* The `cloud-logging` exporter will send data to all found bindings to SAP Cloud Logging.
182
+
The auto-instrumentation of the `otlp` exporter will just configure the first binding it finds priotizing user-provided services.
183
+
* The `otlp` configuration will write the required certificates and keys to temporary files, which are deleted when the JVM is shut down. The `cloud-logging` exporter will keep the secrets in memory.
184
+
* Since the `otlp` exporter is the default for traces and metrics, just attaching the extension and binding to Cloud Logging will result in metrics and traces being forwarded.
185
+
The `cloud-logging` exporter needs to be configured explictly as does the `otlp` exporter for logs.
0 commit comments