SONAR-22479 Create telemetry-core module

8 files changed, 369 insertions, 0 deletions

diff --git a/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/Dimension.java b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/Dimension.java
new file mode 100644
index 00000000000..96f9ce5b5fd
--- /dev/null
+++ b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/Dimension.java
@@ -0,0 +1,54 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Represents the dimension of the data provided by a {@link TelemetryDataProvider}.
+ * {@link Dimension#PROJECT}, {@link Dimension#LANGUAGE} and {@link Dimension#USER} should not provide aggregated data.
+ * For aggregated data (i.e. average number of lines of code per project), use #INSTALLATION.
+ */
+public enum Dimension {
+  INSTALLATION("installation"),
+  USER("user"),
+  PROJECT("project"),
+  LANGUAGE("language");
+
+  private final String value;
+
+  Dimension(String value) {
+    this.value = value;
+  }
+
+  @JsonValue
+  public String getValue() {
+    return value;
+  }
+
+  public static Dimension fromValue(String value) {
+    for (Dimension dimension : Dimension.values()) {
+      if (dimension.value.equalsIgnoreCase(value)) {
+        return dimension;
+      }
+    }
+    throw new IllegalArgumentException("Unknown dimension value: " + value);
+  }
+}
diff --git a/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/Granularity.java b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/Granularity.java
new file mode 100644
index 00000000000..be5cd22bb93
--- /dev/null
+++ b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/Granularity.java
@@ -0,0 +1,44 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Represent the granularity of the data provided by a {@link TelemetryDataProvider}. This both defines the time period between to pushes to
+ * telemetry server for a given metric and the time period that the data represents.
+ * Modifying this enum needs to be discussed beforehand with Data Platform team.
+ */
+public enum Granularity {
+  DAILY("daily"),
+  WEEKLY("weekly"),
+  MONTHLY("monthly");
+
+  private final String value;
+
+  Granularity(String value) {
+    this.value = value;
+  }
+
+  @JsonValue
+  public String getValue() {
+    return value;
+  }
+}
diff --git a/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/TelemetryDataProvider.java b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/TelemetryDataProvider.java
new file mode 100644
index 00000000000..a464014e767
--- /dev/null
+++ b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/TelemetryDataProvider.java
@@ -0,0 +1,78 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import java.util.Map;
+
+/**
+ * This interface is used to provide data to the telemetry system. The telemetry system will call the methods of this interface to get the
+ * data that will be sent to the telemetry server.
+ * If you want to add new metric to the telemetry system, you need to create a new implementation of this interface and register it in the
+ * Spring context as a bean.
+ *
+ * @param <T> type of the value provided by this instance. Should be either {@link Boolean}, {@link String},
+ * {@link Integer} or {@link Float}.
+ */
+public interface TelemetryDataProvider<T> {
+
+  /**
+   * @return the key of the metric that will be used to store the value of the data provided by this instance. The combination of
+   * metric key and dimension needs to be universally unique. The metric key needs to be written in snake_case.
+   */
+  String getMetricKey();
+
+  /**
+   * @return the dimension ("category") of the data provided by this instance. The combination of metric key and dimension needs to be
+   * universally unique.
+   */
+  Dimension getDimension();
+
+  /**
+   * @return returns the granularity of this telemetry metric.
+   * @see Granularity
+   */
+  Granularity getGranularity();
+
+  /**
+   * @return the type of the data provided by this instance.
+   */
+  TelemetryDataType getType();
+
+  /**
+   * The implementation of this method might often need to make a call to a database.
+   * For each metric either this method or {@link TelemetryDataProvider#getUuidValues()} should be implemented and used. Not both at once.
+   *
+   * @return the value of the data provided by this instance.
+   */
+  default T getValue() {
+    throw new IllegalStateException("Not implemented");
+  }
+
+  /**
+   * The implementation of this method might often need to make a call to a database.
+   * Similiar as {@link TelemetryDataProvider#getValue()} this method returns values of the metric. Some of the metrics
+   * associate a UUID with a value. This method is used to return all the values associated with the UUIDs.
+   *
+   * @return map of UUIDs and their values.
+   */
+  default Map<String, T> getUuidValues() {
+    throw new IllegalStateException("Not implemented");
+  }
+}
diff --git a/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/TelemetryDataType.java b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/TelemetryDataType.java
new file mode 100644
index 00000000000..5f096d0dcfa
--- /dev/null
+++ b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/TelemetryDataType.java
@@ -0,0 +1,44 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * Represents the type of the data provided by a {@link TelemetryDataProvider}.
+ * Modifying this enum needs to be discussed beforehand with Data Platform team.
+ */
+public enum TelemetryDataType {
+  BOOLEAN("boolean"),
+  STRING("string"),
+  INTEGER("integer"),
+  FLOAT("float");
+
+  private final String value;
+
+  TelemetryDataType(String value) {
+    this.value = value;
+  }
+
+  @JsonValue
+  public String getValue() {
+    return value;
+  }
+}
diff --git a/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/package-info.java b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/package-info.java
new file mode 100644
index 00000000000..1b573068f64
--- /dev/null
+++ b/server/sonar-telemetry-core/src/main/java/org/sonar/telemetry/core/package-info.java
@@ -0,0 +1,23 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+@ParametersAreNonnullByDefault
+package org.sonar.telemetry.core;
+
+import javax.annotation.ParametersAreNonnullByDefault;
diff --git a/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/DimensionTest.java b/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/DimensionTest.java
new file mode 100644
index 00000000000..6c2c74b5892
--- /dev/null
+++ b/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/DimensionTest.java
@@ -0,0 +1,56 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+class DimensionTest {
+  @Test
+  void getValue() {
+    assertEquals("installation", Dimension.INSTALLATION.getValue());
+    assertEquals("user", Dimension.USER.getValue());
+    assertEquals("project", Dimension.PROJECT.getValue());
+    assertEquals("language", Dimension.LANGUAGE.getValue());
+  }
+
+  @Test
+  void fromValue() {
+    assertEquals(Dimension.INSTALLATION, Dimension.fromValue("installation"));
+    assertEquals(Dimension.USER, Dimension.fromValue("user"));
+    assertEquals(Dimension.PROJECT, Dimension.fromValue("project"));
+    assertEquals(Dimension.LANGUAGE, Dimension.fromValue("language"));
+
+    assertEquals(Dimension.INSTALLATION, Dimension.fromValue("INSTALLATION"));
+    assertEquals(Dimension.USER, Dimension.fromValue("USER"));
+    assertEquals(Dimension.PROJECT, Dimension.fromValue("PROJECT"));
+    assertEquals(Dimension.LANGUAGE, Dimension.fromValue("LANGUAGE"));
+  }
+
+  @Test
+  void fromValue_whenInvalid() {
+    Exception exception = assertThrows(IllegalArgumentException.class, () -> {
+      Dimension.fromValue("invalid");
+    });
+    assertEquals("Unknown dimension value: invalid", exception.getMessage());
+  }
+}
diff --git a/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/GranularityTest.java b/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/GranularityTest.java
new file mode 100644
index 00000000000..a4b01e93305
--- /dev/null
+++ b/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/GranularityTest.java
@@ -0,0 +1,35 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class GranularityTest {
+
+  @Test
+  void getValue() {
+    assertEquals("daily", Granularity.DAILY.getValue());
+    assertEquals("weekly", Granularity.WEEKLY.getValue());
+    assertEquals("monthly", Granularity.MONTHLY.getValue());
+  }
+
+}
diff --git a/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/TelemetryDataTypeTest.java b/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/TelemetryDataTypeTest.java
new file mode 100644
index 00000000000..4749a858364
--- /dev/null
+++ b/server/sonar-telemetry-core/src/test/java/org/sonar/telemetry/core/TelemetryDataTypeTest.java
@@ -0,0 +1,35 @@
+/*
+ * SonarQube
+ * Copyright (C) 2009-2024 SonarSource SA
+ * mailto:info AT sonarsource DOT com
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+ */
+package org.sonar.telemetry.core;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+class TelemetryDataTypeTest {
+  @Test
+  void getValue() {
+    assertEquals("integer", TelemetryDataType.INTEGER.getValue());
+    assertEquals("string", TelemetryDataType.STRING.getValue());
+    assertEquals("boolean", TelemetryDataType.BOOLEAN.getValue());
+    assertEquals("float", TelemetryDataType.FLOAT.getValue());
+  }
+
+}