server-sdk-py: log caller-side error codes below error level

Open Beginner friendly
#2,011 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
75/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
observability

Research direction

Start at _log_level in the Python SDK's errors.py, the single place both the stdlib and [observability] logging paths consult, and list the codes it currently maps to WARNING versus ERROR. Mirror the existing bad_input level test in the tests beside it for each newly demoted code, and cover the auth_required case where upstream_status is set stays at ERROR. Done means caller-side codes log at WARNING, metrics via service_errors_total are untouched, tests pass, and the server-sdk/errors docs page lists the new levels.

Written by the indexing model from the issue text.

Description

needs-triage

Problem

nimblebrain_server_sdk.errors records every surfaced ServiceError as one service_error log line. Only bad_input is logged at WARNING; every other code is logged at ERROR.

A server that returns not_found or conflict through the contract does so in ordinary use: an agent looks up an id that does not exist, or writes to a record whose state refuses the write. Those are the caller's situation, not a server fault, yet each one is an error-level log line. A team that watches error-level logs sees noise proportional to normal traffic.

Proposal

Log the caller-side codes at WARNING: bad_input, not_found, conflict, forbidden, and auth_required when it is the caller's missing identity. Keep ERROR for internal, upstream_unavailable, upstream_timeout, upstream_rejected, quota_exhausted and rate_limited.

Open question: auth_required is used both for a caller with no identity and for an upstream that rejects the server's own credential (ServiceError.from_upstream(401)). The second is an operator's problem and should stay at ERROR. One way to tell them apart is upstream_status being set.

Scope

  • _log_level in errors.py, used by both the standard-library path and the [observability] path.
  • The metric is unchanged: every code still increments service_errors_total.
  • Tests beside the existing bad_input level test; the docs page server-sdk/errors states the levels.

Not urgent: it changes log noise, not behaviour. Fold it into the next SDK release.

Dominant language
TypeScript
Stars
23
Forks
15
Avg merge
4h 28m
Merged PRs (30d)
209

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NimbleBrainInc/nimblebrain

All issues in NimbleBrainInc/nimblebrain

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.