pinpoint-apm/pinpoint · error · IllegalArgumentException

customMetricName must consist of {GroupName}/{MetricName}/La

Error message

customMetricName must consist of {GroupName}/{MetricName}/LabelName}

What it means

CustomMetricIdGenerator.create() requires custom metric names in the strict format {GroupName}/{MetricName}/LabelName. checkValidCustomMetricName splits on '/' with limit 3 and throws IllegalArgumentException if the split does not yield exactly 3 parts.

Source

Thrown at agent-module/profiler/src/main/java/com/navercorp/pinpoint/profiler/context/monitor/metric/CustomMetricIdGenerator.java:76

            }

            boolean contains = metricNameToIdMap.containsKey(metricName);
            if (contains) {
                return NOT_REGISTERED;
            }

            ++currentId;
            metricNameToIdMap.put(metricName, currentId);
            return currentId;
        }
    }

    private boolean checkValidCustomMetricName(String customMetricName) {
        try {
            String[] split = customMetricName.split("/", 3);

            if (split.length != 3) {
                throw new IllegalArgumentException("customMetricName must consist of {GroupName}/{MetricName}/LabelName}");
            }

            for (String eachName : split) {
                if (!IdValidateUtils.validateId(eachName, 64)) {
                    return false;
                }
            }

            return true;
        } catch (Exception e) {
            logger.warn("Inserted customMetricName({}) is not valid. cause:{}", customMetricName, e.getMessage(), e);
        }
        return false;
    }

}

View on GitHub (pinned to 744c3d3075)

Solutions

1. Format the name as GroupName/MetricName/LabelName with exactly two slashes, e.g. 'app/orderCount/success'
2. Ensure each segment passes IdValidateUtils.validateId (alphanumeric allowed chars, max 64 chars)
3. Validate the name with the same split('/')==3 check before calling the API
4. Trim accidental leading/trailing slashes which create empty segments

Example fix

// before
String name = "orderCount";
// after
String name = "MyApp/orderCount/success";

boolean isValidCustomMetricName(String name) {
    String[] parts = name.split("/", 3);
    if (parts.length != 3) return false;
    for (String p : parts) if (!IdValidateUtils.validateId(p, 64)) return false;
    return true;
}

try { generator.create(rawName); } catch (IllegalArgumentException e) { logger.warn("Bad custom metric name '{}': must be Group/Metric/Label", rawName); }

When it happens

Trigger: Calling the custom-metric registration API with a name that has fewer or more than 2 '/' separators — e.g. 'myMetric' or 'group/metric/label/extra'.

Common situations: Developers registering custom metrics forget the label segment, pass a metric name with spaces or extra slashes, or copy a 2-part name from examples of other APM tools.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• value
• negative tick
• Resource attribute `service.name` is required to save OTLP m
• Resource attribute `pinpoint.agentId` is required to save OT
• N:N relationship between fields and tags is not allowed.

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/809f94fd1b39a69b. Report an issue: GitHub.