feat: OpenTelemetry standard attributes

.github/workflows/service-registration.yml

@@ -67,9 +67,20 @@ jobs:
                 run: >
                     ./gradlew runStartUpCheck --info --scan -Denvironment.startServices=true
 
+            -   name: Start OpenTelemetry containers
+                run: |
+                    cd otel
+                    sh/start_containers.sh
+
             -   name: Run startup check for modulith
                 run: >
-                    ./gradlew runStartUpCheck --info --scan -Denvironment.startServices=true -Denvironment.modulith=true -Denvironment.config=-modulith
+                    ./gradlew runStartUpCheckWithOpenTelemetry --info --scan -Denvironment.startServices=true -Denvironment.modulith=true -Denvironment.config=-modulith
+
+            -   name: Validate telemetry data and stop containers
+                if: always()
+                run: |
+                    cd otel
+                    sh/validate_and_stop.sh
 
             -   name: Store results
                 uses: actions/upload-artifact@v4
@@ -78,5 +89,6 @@ jobs:
                     name: Register-${{ env.JOB_ID }}
                     path: |
                         */build/reports/**
+                        otel/**
 
             -   uses: ./.github/actions/teardown

apiml-common/build.gradle

@@ -8,6 +8,7 @@ dependencies {
     implementation libs.spring.boot.starter.actuator
     implementation libs.spring.boot.starter.web
     implementation libs.spring.cloud.starter.eureka.client
+    implementation libs.opentelemetry.spring.boot.starter
     compileOnly libs.netty.reactor.http
     implementation libs.eureka.core
 

apiml-common/src/main/java/org/zowe/apiml/product/opentelemetry/ApimlNonZosOpenTelemetryResourceProvider.java

@@ -0,0 +1,35 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+
+package org.zowe.apiml.product.opentelemetry;
+
+import io.opentelemetry.api.common.Attributes;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.stereotype.Component;
+
+import javax.annotation.Nonnull;
+
+@ConditionalOnMissingBean(ApimlZosOpenTelemetryResourceProvider.class)
+@Component
+public class ApimlNonZosOpenTelemetryResourceProvider extends ApimlOpenTelemetryResourceProvider {
+
+    @Override
+    protected @Nonnull Attributes internalCalculateAttributes() {
+        return Attributes.empty();
+    }
+
+    @Override
+    protected String generateServiceName() {
+        var systemName = StringUtils.isBlank(apimlId) ? hostname : apimlId;
+        return "apiml:" + systemName + ":" + port;
+    }
+
+}

apiml-common/src/main/java/org/zowe/apiml/product/opentelemetry/ApimlOpenTelemetryResourceProvider.java

@@ -0,0 +1,95 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+
+package org.zowe.apiml.product.opentelemetry;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
+import io.opentelemetry.sdk.autoconfigure.spi.ResourceProvider;
+import io.opentelemetry.sdk.resources.Resource;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.factory.annotation.Value;
+
+import javax.annotation.Nonnull;
+
+@Slf4j
+public abstract class ApimlOpenTelemetryResourceProvider implements ResourceProvider {
+
+    public static final String OS_VERSION = "os.version";
+
+    @Value("${otel.resource.attributes.service.namespace:#{null}}")
+    private String serviceNamespace;
+
+    @Value("${apiml.service.hostname:localhost}")
+    protected String hostname;
+
+    @Value("${apiml.service.port:10010}")
+    protected int port;
+
+    @Value("${otel.resource.attributes.service.name:#{null}}")
+    private String serviceName;
+
+    @Value("${apiml.service.apimlId:#{null}}")
+    protected String apimlId;
+
+    public @Nonnull Attributes calculateAttributes() {
+        var attributesBuilder = Attributes.builder();
+
+        if (StringUtils.isBlank(serviceNamespace)) {
+            log.debug("service.namespace is not provided in configuration");
+        }
+
+        if (StringUtils.isBlank(serviceName)) {
+            var generatedServiceName = generateServiceName();
+            attributesBuilder.put("service.name", generatedServiceName);
+            log.debug("service.name not provided in configuration, using generated default {}", generatedServiceName);
+        }
+
+        var instanceId = generateInstanceId();
+        attributesBuilder.put(ZosOpenTelemetryAttributes.OTEL_ZOS_INSTANCE_ID, instanceId);
+        log.debug("using generated service.instance.id {}", instanceId);
+
+        // io.opentelemetry.instrumentation.resources.OsResource resolves the version but uses it only to populate os.description
+        // https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues/16211
+        attributesBuilder.put(OS_VERSION, System.getProperty(OS_VERSION));
+
+        attributesBuilder.putAll(internalCalculateAttributes());
+        return attributesBuilder.build();
+    }
+
+    protected abstract @Nonnull Attributes internalCalculateAttributes();
+
+    @Override
+    public Resource createResource(@Nonnull ConfigProperties config) {
+        var attributesBuilder = Attributes.builder();
+
+        attributesBuilder.putAll(calculateAttributes());
+        return Resource.create(attributesBuilder.build());
+    }
+
+    private String generateInstanceId() {
+        return String.format("%s:gateway:%d", hostname, port);
+    }
+
+    protected abstract String generateServiceName();
+
+    @Override
+    public int order() {
+        /* To run after
+                io.opentelemetry.instrumentation.resources.JarServiceNameDetector
+            but before
+                io.opentelemetry.sdk.autoconfigure.EnvironmentResourceProvider
+                io.opentelemetry.sdk.extension.incubator.resources.ServiceInstanceIdResourceProvider
+        */
+        return 10000;
+    }
+
+}

apiml-common/src/main/java/org/zowe/apiml/product/opentelemetry/ApimlZosOpenTelemetryResourceProvider.java

@@ -0,0 +1,115 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+
+package org.zowe.apiml.product.opentelemetry;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.common.AttributesBuilder;
+import jakarta.annotation.PostConstruct;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.apache.commons.lang3.StringUtils;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Component;
+import org.zowe.apiml.product.zos.ZosSystemInformation;
+
+import javax.annotation.Nonnull;
+
+import java.util.Optional;
+
+import static org.zowe.apiml.product.zos.ZosSystemInformation.ZOS_ENVIRON;
+import static org.zowe.apiml.product.zos.ZosSystemInformation.ZOS_JOB_NAME;
+import static org.zowe.apiml.product.zos.ZosSystemInformation.ZOS_SMF_ID;
+import static org.zowe.apiml.product.zos.ZosSystemInformation.ZOS_SYSNAME;
+import static org.zowe.apiml.product.zos.ZosSystemInformation.ZOS_SYSPLEX;
+import static org.zowe.apiml.product.zos.ZosSystemInformation.ZOS_USER_ID;
+
+@Component
+@RequiredArgsConstructor
+@Profile("zos")
+@Slf4j
+public class ApimlZosOpenTelemetryResourceProvider extends ApimlOpenTelemetryResourceProvider {
+
+    private final ZosSystemInformation zosSystemInformation;
+
+    @Value("${otel.resource.attributes.deployment.environment.name:#{null}}")
+    private String environmentName;
+
+    @Value("${otel.resource.attributes.zos.sysplex.name:#{null}}")
+    private String sysplexName;
+
+    @Value("${otel.resource.attributes.mainframe.lpar.name:#{null}}")
+    private String lparName;
+
+    @Value("${otel.resource.attributes.zos.smf.id:#{null}}")
+    private String smfId;
+
+    @PostConstruct
+    void afterPropertiesSet() {
+        log.debug("Using ZOS OpenTelemetry resource provider");
+    }
+
+    private void attribute(AttributesBuilder attributesBuilder, @Nonnull String openTelemetryAttribute, String zosAttribute) {
+        var zosAttributes = zosSystemInformation.get();
+        var zosValue = zosAttributes.get(zosAttribute);
+        if (zosValue != null && StringUtils.isNotBlank(zosValue.toString())) {
+            log.debug(openTelemetryAttribute + " not provided in configuration, using z/OS obtained {}", zosValue);
+            attributesBuilder.put(openTelemetryAttribute, zosValue.toString());
+        } else {
+            log.debug(openTelemetryAttribute + " not provided in configuration. Could not determine it from system");
+        }
+    }
+
+    @SuppressWarnings("null")
+    @Override
+    @Nonnull
+    protected Attributes internalCalculateAttributes() {
+        var attributesBuilder = Attributes.builder();
+
+        var zosAttributes = zosSystemInformation.get();
+
+        if (StringUtils.isBlank(environmentName)) {
+            attribute(attributesBuilder, "deployment.environment.name", ZOS_ENVIRON);
+        }
+
+        if (StringUtils.isBlank(sysplexName)) {
+            attribute(attributesBuilder, "zos.sysplex.name", ZOS_SYSPLEX);
+        }
+
+        if (StringUtils.isBlank(lparName)) {
+            attribute(attributesBuilder, "mainframe.lpar.name", ZOS_SYSNAME);
+        }
+
+        if (StringUtils.isBlank(smfId)) {
+            attribute(attributesBuilder, "zos.smf.id", ZOS_SMF_ID);
+        }
+
+        Optional.ofNullable(zosAttributes.get(ZOS_JOB_NAME))
+            .map(String::valueOf)
+            .filter(StringUtils::isNotBlank)
+            .ifPresent(zosJobName -> attributesBuilder.put(ZosOpenTelemetryAttributes.OTEL_ZOS_JOBNAME, zosJobName));
+
+        Optional.ofNullable(zosAttributes.get(ZOS_USER_ID))
+            .map(String::valueOf)
+            .filter(StringUtils::isNotBlank)
+            .ifPresent(zosUserId -> attributesBuilder.put(ZosOpenTelemetryAttributes.OTEL_ZOS_USERID, zosUserId));
+
+        return attributesBuilder.build();
+    }
+
+    @Override
+    protected String generateServiceName() {
+        var zosAttributes = zosSystemInformation.get();
+        var systemName = StringUtils.isBlank(apimlId) ? zosAttributes.get(ZOS_SYSPLEX) : apimlId;
+        return "apiml:" + systemName + ":" + port;
+    }
+
+}

apiml-common/src/main/java/org/zowe/apiml/product/opentelemetry/ZosOpenTelemetryAttributes.java

@@ -0,0 +1,22 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+
+package org.zowe.apiml.product.opentelemetry;
+
+/**
+ * Set of attributes set by API ML
+ */
+public class ZosOpenTelemetryAttributes {
+
+    public static final String OTEL_ZOS_JOBNAME = "process.zos.jobname";
+    public static final String OTEL_ZOS_USERID = "process.zos.userid";
+    public static final String OTEL_ZOS_INSTANCE_ID = "service.instance.id";
+
+}

apiml-common/src/test/java/org/zowe/apiml/product/opentelemetry/ApimlNonZosOpenTelemetryResourceProviderTest.java

@@ -0,0 +1,54 @@
+/*
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ */
+
+package org.zowe.apiml.product.opentelemetry;
+
+import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.mockito.Mockito.mock;
+
+@ExtendWith(MockitoExtension.class)
+class ApimlNonZosOpenTelemetryResourceProviderTest {
+
+    private ApimlNonZosOpenTelemetryResourceProvider resourceProvider;
+
+    @BeforeEach
+    void setUp() {
+        this.resourceProvider = new ApimlNonZosOpenTelemetryResourceProvider();
+        ReflectionTestUtils.setField(resourceProvider, "hostname", "localhost");
+        ReflectionTestUtils.setField(resourceProvider, "port", 10010);
+    }
+
+    @Test
+    void testCalculateAttributes() {
+        var result = resourceProvider.calculateAttributes();
+        assertFalse(result.isEmpty());
+    }
+
+    @Test
+    void testCreateResource() {
+        var result = resourceProvider.createResource(mock(ConfigProperties.class));
+        assertFalse(result.getAttributes().isEmpty());
+    }
+
+    @Test
+    void testServiceName() {
+        var result = resourceProvider.generateServiceName();
+        assertEquals("apiml:localhost:10010", result);
+    }
+
+}