YamlHelper.java

/*
 * Copyright The OpenTelemetry Authors
 * SPDX-License-Identifier: Apache-2.0
 */

package io.opentelemetry.instrumentation.docs.utils;

import static java.util.Collections.emptyList;
import static java.util.stream.Collectors.toList;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.dataformat.yaml.YAMLFactory;
import io.opentelemetry.instrumentation.docs.internal.ConfigurationOption;
import io.opentelemetry.instrumentation.docs.internal.ConfigurationType;
import io.opentelemetry.instrumentation.docs.internal.EmittedMetrics;
import io.opentelemetry.instrumentation.docs.internal.EmittedScope;
import io.opentelemetry.instrumentation.docs.internal.EmittedSpans;
import io.opentelemetry.instrumentation.docs.internal.InstrumentationClassification;
import io.opentelemetry.instrumentation.docs.internal.InstrumentationMetadata;
import io.opentelemetry.instrumentation.docs.internal.InstrumentationModule;
import io.opentelemetry.instrumentation.docs.internal.TelemetryAttribute;
import java.io.BufferedWriter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Set;
import java.util.TreeMap;
import java.util.TreeSet;
import org.yaml.snakeyaml.DumperOptions;
import org.yaml.snakeyaml.Yaml;

/**
 * Used for reading and writing Yaml files. This class is responsible for the structure and contents
 * of the instrumentation-list.yaml file.
 */
public class YamlHelper {

  private static final ObjectMapper mapper = new ObjectMapper(new YAMLFactory());

  public static void generateInstrumentationYaml(
      List<InstrumentationModule> list, BufferedWriter writer) {
    DumperOptions options = new DumperOptions();
    options.setDefaultFlowStyle(DumperOptions.FlowStyle.BLOCK);

    Yaml yaml = new Yaml(options);

    Map<String, Object> libraries = getLibraryInstrumentations(list);
    if (!libraries.isEmpty()) {
      yaml.dump(libraries, writer);
    }

    // add custom instrumentation modules
    Map<String, Object> custom = getCustomInstrumentations(list);
    if (!custom.isEmpty()) {
      yaml.dump(custom, writer);
    }
  }

  private static Map<String, Object> getLibraryInstrumentations(List<InstrumentationModule> list) {
    List<InstrumentationModule> libraryInstrumentations =
        list.stream()
            .filter(
                module ->
                    module
                        .getMetadata()
                        .getClassification()
                        .equals(InstrumentationClassification.LIBRARY))
            .sorted(InstrumentationNameComparator.BY_NAME_AND_VERSION)
            .toList();

    if (libraryInstrumentations.isEmpty()) {
      return new TreeMap<>();
    }

    List<Map<String, Object>> instrumentations = new ArrayList<>();
    for (InstrumentationModule module : libraryInstrumentations) {
      instrumentations.add(baseProperties(module));
    }

    Map<String, Object> output = new TreeMap<>();
    output.put("libraries", instrumentations);
    return output;
  }

  private static Map<String, Object> getCustomInstrumentations(List<InstrumentationModule> list) {
    List<InstrumentationModule> filtered =
        list.stream()
            .filter(
                module ->
                    module
                        .getMetadata()
                        .getClassification()
                        .equals(InstrumentationClassification.CUSTOM))
            .sorted(InstrumentationNameComparator.BY_NAME_AND_VERSION)
            .toList();

    List<Map<String, Object>> instrumentations = new ArrayList<>();
    for (InstrumentationModule module : filtered) {
      instrumentations.add(baseProperties(module));
    }

    Map<String, Object> newOutput = new TreeMap<>();
    if (instrumentations.isEmpty()) {
      return newOutput;
    }
    newOutput.put(InstrumentationClassification.CUSTOM.toString(), instrumentations);
    return newOutput;
  }

  /** Assembles map of properties that all modules could have */
  private static Map<String, Object> baseProperties(InstrumentationModule module) {
    Map<String, Object> moduleMap = new LinkedHashMap<>();
    moduleMap.put("name", module.getInstrumentationName());

    addMetadataProperties(module, moduleMap);
    moduleMap.put("source_path", module.getSrcPath());

    if (module.getMinJavaVersion() != null) {
      moduleMap.put("minimum_java_version", module.getMinJavaVersion());
    }

    moduleMap.put("scope", getScopeMap(module));

    if (module.hasStandaloneLibrary()) {
      moduleMap.put("has_standalone_library", true);
    }

    if (module.hasJavaAgent()) {
      moduleMap.put("has_javaagent", true);
    }

    if (module.getAgentTargetVersions() != null && !module.getAgentTargetVersions().isEmpty()) {
      List<String> agentTargetVersions = new ArrayList<>(module.getAgentTargetVersions());
      Collections.sort(agentTargetVersions);
      moduleMap.put("javaagent_target_versions", agentTargetVersions);
    }

    addConfigurations(module, moduleMap);

    // Get telemetry grouping lists
    Set<String> telemetryGroups = new TreeSet<>(module.getMetrics().keySet());
    telemetryGroups.addAll(module.getSpans().keySet());

    if (!telemetryGroups.isEmpty()) {
      List<Map<String, Object>> telemetryList = new ArrayList<>();
      for (String group : telemetryGroups) {
        Map<String, Object> telemetryEntry = new LinkedHashMap<>();
        telemetryEntry.put("when", group);
        List<EmittedMetrics.Metric> metrics =
            new ArrayList<>(module.getMetrics().getOrDefault(group, emptyList()));
        List<Map<String, Object>> metricsList = new ArrayList<>();

        // sort by name for determinism in the order
        metrics.sort(Comparator.comparing(EmittedMetrics.Metric::getName));

        for (EmittedMetrics.Metric metric : metrics) {
          metricsList.add(getMetricsMap(metric));
        }
        if (!metricsList.isEmpty()) {
          telemetryEntry.put("metrics", metricsList);
        }

        List<EmittedSpans.Span> spans =
            new ArrayList<>(module.getSpans().getOrDefault(group, emptyList()));
        List<Map<String, Object>> spanList = new ArrayList<>();

        // sort by name for determinism in the order
        spans.sort(Comparator.comparing(EmittedSpans.Span::getSpanKind));

        for (EmittedSpans.Span span : spans) {
          spanList.add(getSpanMap(span));
        }
        if (!spanList.isEmpty()) {
          telemetryEntry.put("spans", spanList);
        }

        if (!spanList.isEmpty() || !metricsList.isEmpty()) {
          telemetryList.add(telemetryEntry);
        }
      }

      if (!telemetryList.isEmpty()) {
        moduleMap.put("telemetry", telemetryList);
      }
    }
    return moduleMap;
  }

  private static void addMetadataProperties(
      InstrumentationModule module, Map<String, Object> moduleMap) {
    if (module.getMetadata() != null) {
      if (module.getMetadata().getDisplayName() != null) {
        moduleMap.put("display_name", module.getMetadata().getDisplayName());
      }
      if (module.getMetadata().getDescription() != null) {
        moduleMap.put("description", module.getMetadata().getDescription());
      }
      if (module.getMetadata().getSemanticConventions() != null
          && !module.getMetadata().getSemanticConventions().isEmpty()) {
        List<String> conventionNames =
            module.getMetadata().getSemanticConventions().stream()
                .map(Enum::name)
                .collect(toList());
        moduleMap.put("semantic_conventions", conventionNames);
      }
      if (module.getMetadata().getLibraryLink() != null) {
        moduleMap.put("library_link", module.getMetadata().getLibraryLink());
      }
      if (module.getMetadata().getDisabledByDefault()) {
        moduleMap.put("disabled_by_default", module.getMetadata().getDisabledByDefault());
      }
      if (!module.getMetadata().getFeatures().isEmpty()) {
        List<String> functionNames =
            module.getMetadata().getFeatures().stream().map(Enum::name).collect(toList());
        moduleMap.put("features", functionNames);
      }
    }
  }

  private static Map<String, Object> getScopeMap(InstrumentationModule module) {
    Map<String, Object> scopeMap = new LinkedHashMap<>();
    scopeMap.put("name", module.getScopeInfo().getName());
    if (module.getScopeInfo().getSchemaUrl() != null) {
      scopeMap.put("schema_url", module.getScopeInfo().getSchemaUrl());
    }
    if (module.getScopeInfo().getAttributes() != null
        && !module.getScopeInfo().getAttributes().isEmpty()) {
      Map<String, Object> attributesMap = new LinkedHashMap<>();
      module
          .getScopeInfo()
          .getAttributes()
          .forEach((key, value) -> attributesMap.put(key.getKey(), value));
      scopeMap.put("attributes", attributesMap);
    }
    return scopeMap;
  }

  private static void addConfigurations(
      InstrumentationModule module, Map<String, Object> moduleMap) {
    if (module.getMetadata() != null && !module.getMetadata().getConfigurations().isEmpty()) {
      List<Map<String, Object>> configurations = new ArrayList<>();
      for (ConfigurationOption configuration : module.getMetadata().getConfigurations()) {
        configurations.add(configurationToMap(configuration));
      }
      moduleMap.put("configurations", configurations);
    }
  }

  private static Map<String, Object> configurationToMap(ConfigurationOption configuration) {
    Map<String, Object> conf = new LinkedHashMap<>();
    conf.put("name", configuration.name());
    if (configuration.declarativeName() != null) {
      conf.put("declarative_name", configuration.declarativeName());
    }
    conf.put("description", configuration.description());
    conf.put("type", configuration.type().toString());
    if (configuration.type().equals(ConfigurationType.BOOLEAN)) {
      conf.put("default", Boolean.parseBoolean(configuration.defaultValue()));
    } else if (configuration.type().equals(ConfigurationType.INT)) {
      conf.put("default", Integer.parseInt(configuration.defaultValue()));
    } else {
      conf.put("default", configuration.defaultValue());
    }
    if (configuration.examples() != null && !configuration.examples().isEmpty()) {
      conf.put("examples", configuration.examples());
    }
    return conf;
  }

  private static List<Map<String, Object>> getSortedAttributeMaps(
      List<TelemetryAttribute> attributes) {
    List<TelemetryAttribute> sortedAttributes = new ArrayList<>(attributes);
    sortedAttributes.sort(Comparator.comparing(TelemetryAttribute::getName));
    List<Map<String, Object>> attributeMaps = new ArrayList<>();
    for (TelemetryAttribute attribute : sortedAttributes) {
      Map<String, Object> attributeMap = new LinkedHashMap<>();
      attributeMap.put("name", attribute.getName());
      attributeMap.put("type", attribute.getType());
      attributeMaps.add(attributeMap);
    }
    return attributeMaps;
  }

  private static Map<String, Object> getMetricsMap(EmittedMetrics.Metric metric) {
    Map<String, Object> innerMetricMap = new LinkedHashMap<>();
    innerMetricMap.put("name", metric.getName());
    innerMetricMap.put("description", metric.getDescription());
    innerMetricMap.put("instrument", metric.getInstrumentType());
    innerMetricMap.put("data_type", metric.getType());
    innerMetricMap.put("unit", metric.getUnit());
    innerMetricMap.put("attributes", getSortedAttributeMaps(metric.getAttributes()));
    return innerMetricMap;
  }

  private static Map<String, Object> getSpanMap(EmittedSpans.Span span) {
    Map<String, Object> innerMetricMap = new LinkedHashMap<>();
    innerMetricMap.put("span_kind", span.getSpanKind());
    innerMetricMap.put("attributes", getSortedAttributeMaps(span.getAttributes()));
    return innerMetricMap;
  }

  public static InstrumentationMetadata metaDataParser(String input)
      throws JsonProcessingException {
    return mapper.readValue(input, InstrumentationMetadata.class);
  }

  public static EmittedScope emittedScopeParser(String input) {
    return new Yaml().loadAs(input, EmittedScope.class);
  }

  public static EmittedMetrics emittedMetricsParser(String input) throws JsonProcessingException {
    return mapper.readValue(input, EmittedMetrics.class);
  }

  public static EmittedSpans emittedSpansParser(String input) throws JsonProcessingException {
    return mapper.readValue(input, EmittedSpans.class);
  }

  private YamlHelper() {}
}