Upload OpenTelemetry Logs
If you want to ingest logs of your applications or infrastructure instrumented using OpenTelemetry into Oracle Log Analytics, then use the UploadOtlpLogs API to upload them.
The API currently supports OpenTelemetry Logs (OTLP) in JSON format. The OTEL logs uploaded using this API in the specified format are processed using the Oracle-defined OpenTelemetry Logs log source, by default. For more information about the OTLP logs in JSON format, see Examples.
Prerequisites
Ensure that you have completed the following essential prerequisites before uploading the OTEL logs:
- Identify or create a user group to which you can provide the requisite permissions to accomplish upload. See Create User Groups to Implement Access Control.
- Collect OCID of the log group which provides access control for the logs. See Create Log Groups to Store Your Logs.
- Collect the namespace of the tenancy against which the logs must be uploaded. You can note the namespace value from Log Analytics Service Details page. See View Log Analytics Service Details.
Topics:
Allow Users to Upload OpenTelemetry Logs
Add any one of the following IAM policy statements based on your requirement:
-
The following IAM policy statement is for providing permission to the specified user group for uploading the OTEL logs:
allow group <group_name> to {LOG_ANALYTICS_LOG_GROUP_UPLOAD_LOGS} in compartment <log_group_compartment> -
The following IAM policy statement is for providing permission at the level of individual resource-type
loganalytics-log-groupfor performing the upload:allow group <group_name> to use loganalytics-log-group in compartment <log_group_compartment> -
The following IAM policy statement is for providing permission at Oracle Log Analytics aggregate resources level for performing the upload:
allow group <group_name> to use loganalytics-resources-family in tenancy/compartment
group_name in all the above policy statements refers to the user group that must be given the required permissions.
API for Uploading OpenTelemetry Logs
For information about using the REST API and signing requests, see REST APIs and Security Credentials.
For API documentation, see Log Analytics API- UploadOtlpLogs.
Here's an example CLI command to upload OTEL logs:
oci log-analytics upload upload-otlp-logs --file <Log_File_Path> --opc-meta-loggrpid <Log_Group_OCID> --namespace-name <Service_Namespace>In the above command:
Log_File_Path: The path of the log file.Service_Namespace: The namespace of the tenancy against which the logs must be uploaded. For steps to obtain the value, see View Log Analytics Service Details.Log_Group_OCID: The OCID of the log group which provides access control for the logs.
Handling OTEL Attributes in Log Analytics
Attributes can be set at three levels- resource, scope, individual log record. The set attributes are stored for each Log Record against Attributes field of Log Analytics. Each attribute can also be extracted into different Log Analytics field using the custom attribute oci_la_attribute_mapping.
Topics:
- Scenario 1: Default OTLP Log Format and Its Extraction
- Scenario 2: Custom Mapping of Attributes Using Special Attribute oci_la_attribute_mapping
- Scenario 3 : Handling Complex Attributes Mapping
Scenario 1: Default OTLP Log Format and Its Extraction
Consider the following example log in OTLP format:
{
"resourceLogs": [
{
"resource": {
"attributes": [
{
"key": "deployment.environment",
"value": {
"stringValue": "development"
}
},
{
"key": "service.name",
"value": {
"stringValue": "SampleLogApp"
}
},
{
"key": "service.version",
"value": {
"stringValue": "0.0.2"
}
}
]
},
"scopeLogs": [
{
"scope": {
"name": "sample-scope-info",
"version": "1.0.0"
},
"logRecords": [
{
"timeUnixNano": "1758112881118549000",
"severityNumber": 10,
"severityText": "INFO",
"body": {
"stringValue": "Processed request successfully"
},
"attributes": [
{
"key": "event_type",
"value": {
"stringValue": "event-info"
}
},
{
"key": "os",
"value": {
"stringValue": "linux"
}
},
{
"key": "custom_attribute",
"value": {
"stringValue": "some_value"
}
},
{
"key": "dropped",
"value": {
"stringValue": "value"
}
},
{
"key": "otel.dropped_attributes_count",
"value": {
"intValue": "5"
}
},
{
"key": "id",
"value": {
"stringValue": "123"
}
}
],
"traceId": "0102030405060708090a0b0c0d0e0f10",
"spanId": "0102030405060708"
}
]
}
]
}
]
}The attributes from the above example are extracted into Attributes field in Oracle Log Analytics as following:
{
"service.version":"0.0.2",
"os":"linux",
"dropped":"value",
"id":"123",
"custom_attribute":"some_value",
"otel.dropped_attributes_count":"5"
}Scenario 2: Custom Mapping of Attributes Using Special Attribute oci_la_attribute_mapping
For example, to map the following attributes to Oracle Log Analytics fields:
- service.name to the field Application
- deployment.environment to the field Environment
- event_type to the field Event Type.
oci_la_attribute_mapping should be defined as following:
[{"attributeName":"service.name","laFieldName":"Application"},{"attributeName":"deployment.environment","laFieldName":"Environment"},{"attributeName":"event_type","laFieldName":"Event Type"}]Here's an example of the above custom mapping incorporated in the OTEL log:
{
"resourceLogs": [
{
"resource": {
"attributes": [
{
"key": "deployment.environment",
"value": {
"stringValue": "development"
}
},
{
"key": "service.name",
"value": {
"stringValue": "SampleLogApp"
}
},
{
"key": "service.version",
"value": {
"stringValue": "0.0.2"
}
},
{
"key": "oci_la_attribute_mapping",
"value": {
"stringValue": "[{\"attributeName\":\"service.name\",\"laFieldName\":\"Application\"},{\"attributeName\":\"deployment.environment\",\"laFieldName\":\"Environment\"},{\"attributeName\":\"event_type\",\"laFieldName\":\"Event Type\"}]"
}
}
]
},
"scopeLogs": [
{
"scope": {
"name": "sample-scope-info",
"version": "1.0.0"
},
"logRecords": [
{
"timeUnixNano": "1758112881118549000",
"severityNumber": 10,
"severityText": "INFO",
"body": {
"stringValue": "Processed request successfully"
},
"attributes": [
{
"key": "event_type",
"value": {
"stringValue": "event-info"
}
},
{
"key": "os",
"value": {
"stringValue": "linux"
}
},
{
"key": "custom_attribute",
"value": {
"stringValue": "value"
}
},
{
"key": "dropped",
"value": {
"stringValue": "value"
}
},
{
"key": "otel.dropped_attributes_count",
"value": {
"intValue": "5"
}
},
{
"key": "id",
"value": {
"stringValue": "123"
}
}
],
"traceId": "0102030405060708090a0b0c0d0e0f10",
"spanId": "0102030405060708"
}
]
}
]
}
]
}Scenario 3 : Handling Complex Attributes Mapping
Array Attributes (Multi-value):
For an attribute with an array (list) value, ensure that the mapped Oracle Log Analytics field supports multi-valued data types, for example:
{"key": "teams", "value": {"arrayValue": {"values": [{"stringValue": "Alpha"}, {"stringValue": "Beta"}]}}}Map Attributes (Nested Key-Value):
For a map (object) attribute, specify the child key to map it to the Oracle Log Analytics field.
Example list attribute:
{
"key": "system",
"value": {
"kvlistValue": {
"values": [
{
"key": "version",
"value": {
"stringValue": "1.0"
}
},
{
"key": "build",
"value": {
"stringValue": "2.0"
}
},
{
"key": "env",
"value": {
"stringValue": "test"
}
}
]
}
}
}Example mapping in oci_la_attribute_mapping for the above list attribute:
[{"attributeName":"system","childAttributeName":"env","laFieldName":"Environment"}]