Skip to content
Merged
Show file tree
Hide file tree
Changes from 22 commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
0f25ad4
chore: migrate from flint v1 (super-linter) to flint v2 binary
zeitlinger Apr 8, 2026
d39fbc7
chore: update renovate-tracked-deps for flint v2 tools
zeitlinger Apr 8, 2026
8653637
chore: use full multi-line license header text
zeitlinger Apr 8, 2026
63b8ce0
fix: refresh flint v2 migration
zeitlinger Apr 21, 2026
ba9c472
fix: keep fix alias and align license header text
zeitlinger Apr 21, 2026
bb734ab
chore: switch flint migration to v0.20.3
zeitlinger Apr 21, 2026
fc7b442
ci: normalize flint init output
zeitlinger Apr 21, 2026
9727c12
ci: keep markdownlint exceptions local
zeitlinger Apr 21, 2026
a48cf1e
Merge origin/main into feat/flint-v2-migration
zeitlinger Apr 21, 2026
4974ccc
chore: simplify lint tasks
zeitlinger Apr 21, 2026
e43dea7
docs: clarify markdown line length policy
zeitlinger Apr 21, 2026
2431a8f
chore: clarify tool grouping
zeitlinger Apr 21, 2026
54df30f
chore: separate tools from linters
zeitlinger Apr 21, 2026
547e2c7
chore: group flint with linters
zeitlinger Apr 21, 2026
d906733
chore: drop redundant tools heading
zeitlinger Apr 21, 2026
361ff3d
chore: tighten mise tool spacing
zeitlinger Apr 21, 2026
e284979
chore: drop pre-commit setup task
zeitlinger Apr 21, 2026
cda1842
chore: preserve markdownlint config
zeitlinger Apr 21, 2026
8b4d549
chore: replace spotless with flint linting
zeitlinger Apr 21, 2026
1db27cb
chore: refresh renovate tracked deps
zeitlinger Apr 21, 2026
cf4b158
chore: restore markdownlint config
zeitlinger Apr 21, 2026
d5201b8
chore: scope line length by file type
zeitlinger Apr 21, 2026
0d8f17a
chore: enforce markdown line length
zeitlinger Apr 21, 2026
07ce173
chore: apply prettier fixes
zeitlinger Apr 21, 2026
e67342b
chore: tighten line length enforcement
zeitlinger Apr 21, 2026
0f792e6
chore: apply prettier fixes
zeitlinger Apr 21, 2026
2b54954
chore: restore upstream reference
zeitlinger Apr 21, 2026
5f93725
chore: apply java formatting
zeitlinger Apr 21, 2026
90265a8
docs: align markdown lint guidance
zeitlinger Apr 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .editorconfig
Original file line number Diff line number Diff line change
@@ -1,7 +1,49 @@
root = true

[*]
max_line_length = 100
indent_size = 2

[*.md]
max_line_length = 200

[*.yml]
max_line_length = 200

[*.yaml]
max_line_length = 200

[*.json]
max_line_length = 120

[*.json5]
max_line_length = 120

[Dockerfile*]
max_line_length = 200

[{*.gradle,build.gradle,settings.gradle}]
max_line_length = 150

[*.xml]
max_line_length = 200

[build.gradle]
indent_size = 2

[*.java]
max_line_length = 230
indent_size = 2

# ktlint overrides
[{*.kt,*.kts}]
max_line_length = 160
continuation_indent_size = 2
ktlint_standard_no-wildcard-imports = disabled
ktlint_standard_package-name = disabled
ktlint_standard_max-line-length = disabled
ktlint_standard_trailing-comma-on-call-site = disabled
ktlint_standard_trailing-comma-on-declaration-site = disabled
ktlint_standard_wrapping = disabled
ktlint_standard_property-naming = disabled
ktlint_standard_function-literal = disabled
17 changes: 17 additions & 0 deletions .github/config/flint.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[settings]
exclude = [
"CHANGELOG.md",
"gradlew",
Comment thread
zeitlinger marked this conversation as resolved.
]

[checks.license-header]
text = """
/*
* Copyright Grafana Labs
* SPDX-License-Identifier: Apache-2.0
*/
"""
Comment thread
zeitlinger marked this conversation as resolved.
patterns = ["**/*.java", "**/*.kt"]
Comment thread
zeitlinger marked this conversation as resolved.

[checks.renovate-deps]
exclude_managers = ["github-actions", "github-runners"]
29 changes: 0 additions & 29 deletions .github/config/super-linter.env

This file was deleted.

19 changes: 13 additions & 6 deletions .github/renovate-tracked-deps.json
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,6 @@
},
"build.gradle": {
"gradle": [
"com.diffplug.spotless:spotless-plugin-gradle",
"com.google.auto.service:auto-service",
"com.google.auto.service:auto-service-annotations",
"com.gradleup.shadow:shadow-gradle-plugin",
Expand Down Expand Up @@ -66,15 +65,23 @@
},
"mise.toml": {
"mise": [
"actionlint",
"cargo:xmloxide",
"editorconfig-checker",
"github:google/google-java-format",
"github:grafana/flint",
"github:pinterest/ktlint",
"hadolint",
"java",
"lychee",
"node",
"npm:@biomejs/biome",
"npm:markdownlint-cli2",
"npm:prettier",
"npm:renovate",
"ubi:google/google-java-format"
],
"regex": [
"ghcr.io/super-linter/super-linter",
"grafana/flint"
"pipx:codespell",
"shellcheck",
"shfmt"
]
},
"scripts/otel_operator/Dockerfile": {
Expand Down
2 changes: 1 addition & 1 deletion .github/renovate.json5
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
extends: [
"config:best-practices",
"config:recommended",
"github>grafana/flint",
"github>grafana/flint#v0.20.3",
],
platformCommit: "enabled",
automerge: true,
Expand Down
64 changes: 48 additions & 16 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,58 +1,88 @@
# AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.
This file provides guidance to AI coding agents when working
with code in this repository.

## What This Is

A javaagent distribution of the [OpenTelemetry Java instrumentation agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation), optimized for Grafana Cloud Application Observability. It wraps the upstream agent and adds Grafana-specific extensions (tested instrumentation filtering, metric filtering, resource attribute truncation, default config).
A javaagent distribution of the
[OpenTelemetry Java instrumentation
agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation),
optimized for Grafana Cloud Application Observability. It
wraps the upstream agent and adds Grafana-specific
extensions (tested instrumentation filtering, metric
filtering, resource attribute truncation, default config).

## Build Commands

```sh
./gradlew build # full build (compiles, tests, assembles agent JAR)
./gradlew spotlessApply # auto-format Java (Google Java Format) and misc files
mise run lint:fix # auto-fix Java/Markdown/YAML/shell lint issues via flint
./gradlew :custom:test # run unit tests only
./gradlew :custom:test --tests '*MetricFilterTest' # run a single test class
SMOKE_TEST_JAVA_VERSION=8 ./gradlew :smoke-tests:test # run smoke tests (requires env var)
```

The final artifact is `agent/build/libs/grafana-opentelemetry-java.jar`.

Smoke tests only run when `SMOKE_TEST_JAVA_VERSION` env var is set (or running in IntelliJ). They use TestContainers and test the entire javaagent with a real application.
Smoke tests only run when `SMOKE_TEST_JAVA_VERSION` env var
is set (or running in IntelliJ). They use TestContainers
and test the entire javaagent with a real application.

## Modules

- **`:custom`** — Grafana extensions: instrumentation filtering, metric filtering, resource truncation, version logging. Entry point is `GrafanaAutoConfigCustomizerProvider` (implements OpenTelemetry's `AutoConfigurationCustomizerProvider` SPI). Has checkstyle enforcement.
- **`:agent`** — Packages the upstream OTEL javaagent + custom extensions into a single shadow JAR via a 3-step process (relocate → isolate → merge) to avoid classpath conflicts.
- **`:smoke-tests`** — Integration tests using TestContainers that run a Spring Boot app with the full javaagent attached.
- **`:custom`** — Grafana extensions: instrumentation
filtering, metric filtering, resource truncation, version
logging. Entry point is
`GrafanaAutoConfigCustomizerProvider` (implements
OpenTelemetry's `AutoConfigurationCustomizerProvider`
SPI). Has checkstyle enforcement.
- **`:agent`** — Packages the upstream OTEL javaagent +
custom extensions into a single shadow JAR via a 3-step
process (relocate → isolate → merge) to avoid classpath
conflicts.
- **`:smoke-tests`** — Integration tests using
TestContainers that run a Spring Boot app with the full
javaagent attached.

## Architecture

The distro extends upstream OTEL via the `AutoConfigurationCustomizerProvider` SPI. Key customization points in `:custom`:
The distro extends upstream OTEL via the
`AutoConfigurationCustomizerProvider` SPI. Key
customization points in `:custom`:

- `TestedInstrumentationsCustomizer` — optionally limits active instrumentations to a curated list in `Instrumentations.java` (controlled by `grafana.otel.use-tested-instrumentations` property)
- `TestedInstrumentationsCustomizer` — optionally limits
active instrumentations to a curated list in
`Instrumentations.java` (controlled by
`grafana.otel.use-tested-instrumentations` property)
- `MetricsCustomizer` / `MetricFilter` — filters metrics
- `ResourceCustomizer` — truncates resource attribute values (default 2048 chars)
- `DistributionVersion.java` — **auto-generated** by `custom/build.gradle` `manageVersionClass` task; do not edit manually
- `DistributionVersion.java` — **auto-generated** by
`custom/build.gradle` `manageVersionClass` task; do not
edit manually

Package relocation (`gradle/shadow.gradle`) moves OpenTelemetry classes to `io.opentelemetry.javaagent.shaded.*` to prevent conflicts with instrumented application code. Resource providers are excluded from relocation.
Package relocation (`gradle/shadow.gradle`) moves
OpenTelemetry classes to
`io.opentelemetry.javaagent.shaded.*` to prevent conflicts
with instrumented application code. Resource providers are
excluded from relocation.

## Linting

After modifying non-Java files (Markdown, YAML, Dockerfiles, shell scripts, etc.), always run linting via mise:

```sh
mise run lint:super-linter # run super-linter only
mise run fix # auto-fix lint issues
mise run lint # run lint checks
mise run lint:fix # auto-fix lint issues
Comment thread
zeitlinger marked this conversation as resolved.
```

Lint tasks are sourced from [grafana/flint](https://github.com/grafana/flint).

## Code Conventions

- Java 8 compilation target (`-Werror`), Java 17 for tests
- Google Java Format via Spotless, checkstyle (Google style) on `:custom`
- License header: Apache 2.0 / Grafana Labs (enforced by Spotless)
- Google Java Format, ktlint, and checkstyle (Google style) on `:custom`
- License header: Apache 2.0 / Grafana Labs (enforced by flint)
- Package root: `com.grafana.extensions.*`
Comment thread
zeitlinger marked this conversation as resolved.
- JUnit 5 + AssertJ for assertions, LogUnit for log capture

Expand All @@ -67,5 +97,7 @@ Lint tasks are sourced from [grafana/flint](https://github.com/grafana/flint).
## Dependency Management

- Upstream OTEL version tracked in `build.gradle` → `otelInstrumentationVersion`
- Renovate manages dependency updates; extends `github>grafana/flint` preset for mise task and tool version updates (see `.github/renovate.json5`)
- Renovate manages dependency updates; extends
`github>grafana/flint` preset for mise task and tool
version updates (see `.github/renovate.json5`)
- `mise.toml` manages tool versions (Java, lychee) and lint tasks
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ javaagent.jar as well as our custom extension.

## Code formatting

- Java: `./gradlew spotlessApply`
- Java and repo lint fixes: `mise run lint:fix`
- Markdown lint: `markdownlint -f .` (`-f` fixes simple violations, requires [markdownlint](https://github.com/DavidAnson/markdownlint#markdownlint))
- Markdown link checker: `lychee --include-fragments --max-retries 6 .`
(requires [lychee](https://github.com/lycheeverse/lychee))
Expand Down
7 changes: 7 additions & 0 deletions biome.jsonc
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
// Keep JSON formatting aligned with the repo's two-space style.
"formatter": {
"indentStyle": "space",
"indentWidth": 2
}
}
28 changes: 0 additions & 28 deletions build.gradle
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ buildscript {
}
}
dependencies {
classpath "com.diffplug.spotless:spotless-plugin-gradle:8.4.0"
classpath "com.gradleup.shadow:shadow-gradle-plugin:9.4.1"
classpath "io.opentelemetry.instrumentation:gradle-plugins:${otelInstrumentationVersion}-alpha"
}
Expand All @@ -21,7 +20,6 @@ subprojects {
version = rootProject.version

apply plugin: "java"
apply plugin: "com.diffplug.spotless"

ext {
versions = [
Expand All @@ -48,32 +46,6 @@ subprojects {
mavenCentral()
}

spotless {
java {
googleJavaFormat()
licenseHeaderFile(rootProject.file("buildscripts/spotless.license.java"), "(package|import|public)")
target("src/**/*.java")
}

format 'misc', {
// not using "**/..." to help keep spotless fast
target(
".gitignore",
".gitattributes",
".gitconfig",
".editorconfig",
"*.md",
"src/**/*.md",
"docs/**/*.md",
"*.sh",
"src/**/*.properties",
)
leadingTabsToSpaces()
trimTrailingWhitespace()
endWithNewline()
}
}

dependencies {
// these serve as a test of the instrumentation boms
implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:${versions.opentelemetryJavaagentAlpha}"))
Expand Down
5 changes: 0 additions & 5 deletions buildscripts/spotless.license.java

This file was deleted.

Loading
Loading