tdfs4ds.agentops.log_insights¶
Turn a pod log into findings.
An AgentOps pod log is long, mostly build noise, and the line that matters is rarely the last one. Worse, the interesting failures do not look like the thing they are: a pip resolution error means the build never reached your code at all; a fluent answer with no catalog names in it means the pod never reached Teradata.
So this is a signature table, in the shape :func:tdfs4ds.diagnostics._match_hint
already uses elsewhere: substrings that identify a condition, plus the insight
that explains what it actually means and what to do. Every entry below was
observed driving real deployments, not imagined — which is why the table is
short and each row earns its place.
Two design points worth keeping:
A positive signature is not decoration. startup_ok fires on the tdfs4ds
configuration block. "No known failure was found" and "the agent started
correctly" are different conclusions, and only the second is evidence. Without
it, a truncated log and a healthy one are indistinguishable.
Severity is about the deployment, not the wording. A WARNING line that
means the pod cannot answer anything is an error here; an alarming-looking line
that the code already recovers from is not.
module-attribute
¶
_SIGNATURES = (('pip_unresolvable', ERROR, (('no matching distribution', 'tdfs4ds'), ('could not find a version', 'tdfs4ds'), ('no matching distribution found for tdfs4ds',)), 'The image build could not install tdfs4ds, so the pod never ran your code at all. The version pinned in requirements.txt is not on the index the build uses. Publish it, or install from a mirror that carries it.'), ('agent_runtime_missing', ERROR, (("no module named 'agent_runtime'",), ("cannot import name 'agentruntimeapp'",)), 'The platform runtime library is in neither the uploaded zip nor the base image. It is provided by AgentOps, not by tdfs4ds: copy agent_runtime/ from a demo_agents/ template into the agent directory before packaging.'), ('no_credentials', ERROR, (('reconnect_teradata: no usable credentials',), ('tdfs4ds_td_* credentials not configured',)), "The pod has no Teradata credentials, so runtime_config did not reach it. Check that the deployment payload's runtime_config was non-empty. If this environment authenticates with a token rather than a password, deploy with auth='jwt' so the caller's own token is used."), ('token_rejected', ERROR, (('sqlstate 28000',), ('the userid, password or account is invalid',)), "Teradata refused the credential. Under auth='jwt' that usually means the caller's token expired or the caller cannot log on to the database; under auth='service' it means the username/password in runtime_config is wrong."), ('host_unresolved', ERROR, (('name or service not known',), ('getaddrinfo',), ('nodename nor servname',), ('temporary failure in name resolution',)), "TDFS4DS_TD_HOST does not resolve from inside the pod. A bare name like 'dbc' is completed by the resolver's search domains, and an AgentOps pod need not share the notebook's - so a host that works in the notebook can fail here. Try the fully-qualified in-cluster form first (<service>.<namespace>.svc.cluster.local, as the other services use), and if NO name resolves, set TDFS4DS_TD_HOST to the database's IP ADDRESS: verified working from an AgentOps pod, where DNS for the database was not available at all. Note an IP pins the deployment to an address that can change, so re-check it if the pod later stops connecting. A failure in well under a second is the tell: a genuinely unreachable host takes a TCP timeout, a rejected credential reports SQLSTATE 28000."), ('connect_failed', ERROR, (('tdml_2000',), ('failed to connect to teradata vantage',)), "The pod could not open a Teradata session. If no SQLSTATE 28000 appears above, nothing was REFUSED - the connection itself never landed, so suspect TDFS4DS_TD_HOST first: the notebook and the pod are different workloads and need not resolve the same name. Under auth='jwt' also check that the platform's auth_context.token is actually usable as a Vantage JWT (logmech='JWT', logdata='token=...'): a token minted for the AgentOps API is not necessarily accepted by the database, and a pod cannot mint one of its own. Where it is not, auth='jwt' is not deployable in that environment and auth='service' with a real account is the way in."), ('schema_missing', ERROR, (('3807',), ('object', 'does not exist'), ('does not exist or is not authorized',)), 'The pod reached Teradata but cannot see an object it needs. Almost always the feature store named at deploy time is not readable by the identity the pod connects as — compare the database in the startup configuration block against what you passed as database=.'), ('structured_output', ERROR, (('invalid json: expected value at line 1 column 1',), ('validation error for intentresult',)), "The model returned prose or markdown-fenced JSON and the strict parser rejected it: the gateway relays response_format without enforcing it. Set TDFS4DS_STRUCTURED_OUTPUT_METHOD='function_calling' - the structure travels as tool-call arguments, which a relaying gateway forwards intact. json_mode is NOT a safe default here: measured live on a LiteLLM/Bedrock route, response_format is inert in every shape (json_object included), so json_mode gets prose back and fails too."), ('vector_store_auth', WARNING, (('tdml_2412',), ('no base url configured',), ('vector store', 'not enabled')), 'The Teradata Vector Store is unreachable or unauthenticated, so semantic search is degraded — the agent still answers from the catalog and business dictionary. Supply the TDFS4DS_VECTOR_STORE_AUTH_* group in runtime_config.'), ('oom', ERROR, (('oomkilled',), ('memoryerror',), ('killed',)), 'The container ran out of memory. tdfs4ds pulls teradataml, langchain and pandas: 512Mi is not enough. Deploy with at least 2Gi.'), ('startup_ok', INFO, (('tdfs4ds configuration check',), ('agentops deployment preflight',)), 'The agent reached its own configuration check, so the package installed, imported and connected. Read that block for the database and models the pod actually resolved.'))
Return findings for a pod log.
Parameters¶
text : str
Raw log text, as returned by GET /agents/{id}/logs.
max_excerpt : int
Per-finding excerpt cap. The excerpt is the first matching line, which
for a stack trace is the one naming the cause rather than the innermost
frame.
Returns¶
list of dict
{"name", "severity", "insight", "excerpt"}, errors first then
warnings then info, in table order within each severity. Empty when
nothing matched — which is itself a finding the caller should report as
"no known signature", never as "healthy".
The most specific line the group identifies, trimmed.
Prefers a line carrying every marker, because a single broad marker
matches the wrong line: 'tdfs4ds' alone hits Collecting tdfs4ds==... pages
before the No matching distribution that is the actual cause. Falls back
to the longest marker so the excerpt still points somewhere useful.
Render findings as aligned plain text. ASCII only.
A deployment report is read on whatever console the notebook happens to have, and is often saved to a file: the same reason the rest of tdfs4ds keeps generated artifacts ASCII.
True when the log confirms startup and shows no error-severity finding.