diff options
Diffstat (limited to 'server/sonar-telemetry-core')
9 files changed, 393 insertions, 0 deletions
diff --git a/server/sonar-telemetry-core/build.gradle b/server/sonar-telemetry-core/build.gradle new file mode 100644 index 00000000000..010d750923a --- /dev/null +++ b/server/sonar-telemetry-core/build.gradle @@ -0,0 +1,24 @@ +description = 'Module providing the core classes and interfaces for telemetry metrics in SonarQube.' + +sonar { + properties { + property 'sonar.projectName', "${projectTitle} :: Server :: Telemetry Core" + } +} + +dependencies { + compileOnlyApi 'com.github.spotbugs:spotbugs-annotations' + + implementation 'com.fasterxml.jackson.core:jackson-databind' + + testImplementation(platform("org.junit:junit-bom:5.9.1")) + testImplementation 'org.assertj:assertj-core' + testImplementation 'org.junit.jupiter:junit-jupiter-api' + testImplementation 'org.junit.jupiter:junit-jupiter-params' + + testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine' +} + +tasks.test { + useJUnitPlatform() +}
\ No newline at end of file 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()); + } + +} |