{"record":{"id":"10a0c998334525c5","repo":"apache/pulsar","slug":"proxy-log-level-can-be-only-0-2","errorCode":null,"errorMessage":"Proxy log level can be only [0-2]","messagePattern":"Proxy log level can be only \\[0-2\\]","errorType":"http","errorClass":"RestException","httpStatus":412,"severity":"warning","filePath":"pulsar-proxy/src/main/java/org/apache/pulsar/proxy/stats/ProxyStats.java","lineNumber":118,"sourceCode":"            @ApiResponse(responseCode = \"503\", description = \"Proxy service is not initialized\") })\n    public Map<String, TopicStats> topics() {\n        throwIfNotSuperUser(\"topics\");\n        Optional<Integer> logLevel = proxyService().getConfiguration().getProxyLogLevel();\n        if (!logLevel.isPresent() || logLevel.get() < 2) {\n            throw new RestException(Status.PRECONDITION_FAILED, \"Proxy doesn't have logging level 2\");\n        }\n        return proxyService().getTopicStats();\n    }\n\n    @POST\n    @Path(\"/logging/{logLevel}\")\n    @Operation(hidden = true, summary = \"Change proxy logging level dynamically\",\n            description = \"It only changes the log level in memory; change it in the config file to persist the change\")\n    @ApiResponses(value = { @ApiResponse(responseCode = \"412\", description = \"Proxy log level can be [0-2]\"), })\n    public void updateProxyLogLevel(@PathParam(\"logLevel\") int logLevel) {\n        throwIfNotSuperUser(\"updateProxyLogLevel\");\n        if (logLevel < 0 || logLevel > 2) {\n            throw new RestException(Status.PRECONDITION_FAILED, \"Proxy log level can be only [0-2]\");\n        }\n        proxyService().setProxyLogLevel(logLevel);\n    }\n\n    @GET\n    @Path(\"/logging\")\n    @Operation(hidden = true, summary = \"Get proxy logging\")\n    public int getProxyLogLevel(@PathParam(\"logLevel\") int logLevel) {\n        throwIfNotSuperUser(\"getProxyLogLevel\");\n        return proxyService().getProxyLogLevel();\n    }\n\n    protected ProxyService proxyService() {\n        if (service == null) {\n            service = (ProxyService) servletContext.getAttribute(ATTRIBUTE_PULSAR_PROXY_NAME);\n            if (service == null) {\n                throw new RestException(Status.SERVICE_UNAVAILABLE, \"Proxy service is not initialized\");\n            }","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-proxy/src/main/java/org/apache/pulsar/proxy/stats/ProxyStats.java#L100-L136","documentation":"The proxy log level is an in-memory tuning knob restricted to the range 0-2 (0=off, 1=event, 2=verbose/topic stats). ProxyStats.updateProxyLogLevel validates the path parameter before applying it and returns 412 for out-of-range values, since the proxy cannot express levels outside this range.","triggerScenarios":"POST /admin/v2/proxy-stats/logging/{logLevel} with a logLevel < 0 or > 2 (e.g. 3 or -1); a script or dashboard templating an unsupported default level; an operator guessing levels follow java.util.logging or log4j scales (e.g. 4 for DEBUG).","commonSituations":"Automation using log4j-style numeric levels instead of the proxy's 0-2 scale; typos in runbooks; misconfigured alerting that attempts to 'increase to level 3' for more verbosity.","solutions":["Use a value between 0 and 2 inclusive — send POST /logging/2 for maximum verbosity","Update scripts/runbooks to translate desired verbosity into the 0-2 scale","If finer-grained log control is needed, adjust the underlying logback/log4j configuration instead of the proxy REST knob","Remember the change is in-memory only; also set proxyLogLevel in the config file to persist"],"exampleFix":"// before\ncurl -X POST .../proxy-stats/logging/3\n\n// after\ncurl -X POST .../proxy-stats/logging/2","handlingStrategy":"validation","validationCode":"public void setProxyLogLevelSafe(ProxyStats stats, int level) {\n    if (level < 0 || level > 2) {\n        throw new IllegalArgumentException(\"Proxy log level must be within [0-2], got \" + level);\n    }\n    stats.updateProxyLogLevel(level);\n}","typeGuard":"boolean isValidProxyLogLevel(int level) {\n    return level >= 0 && level <= 2;\n}","tryCatchPattern":"try {\n    proxyStats.updateProxyLogLevel(requestedLevel);\n} catch (RestException e) {\n    if (e.getResponseStatus() == 412) {\n        LOG.warn(\"Requested log level {} out of range; using 1\", requestedLevel);\n        proxyStats.updateProxyLogLevel(1);\n    } else {\n        throw e;\n    }\n}","preventionTips":["Clamp/validate log level input to 0-2 in any dashboard or automation that calls POST /logging/{level}","Do not map log4j/logback levels onto this 0-2 proxy scale","Document the valid range in operational runbooks","Persist desired level in proxyLogLevel config instead of setting unsupported values at runtime"],"tags":["pulsar-proxy","rest-api","logging","validation","api-misuse"],"backgroundTag":"invalid-parameter-value","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}