Custom Attributes

neatlogs.* attributes for TOOL, RETRIEVER, RERANKER, GUARDRAIL, and VECTOR_STORE spans.

When building custom logic, set neatlogs.* attributes on your spans so the dashboard can render the right visualizations. These are the same attributes automatically populated by supported libraries — setting them manually on custom implementations gives you identical dashboard views.

TOOL

The @span(kind="TOOL", tool_name="...", description="...") decorator sets these automatically. Use the context manager when you need finer control:

import neatlogs

with neatlogs.trace("search_web", kind="TOOL") as span:
    span.set_attribute("neatlogs.tool.name", "search_web")
    span.set_attribute("neatlogs.tool.description", "Search the web for information")
    result = my_search_api(query)

Attribute	Type	Description
`neatlogs.tool.name`	`str`	Tool identifier
`neatlogs.tool.description`	`str`	What the tool does
`neatlogs.tool.parameters`	`str` (JSON)	Parameter schema

RETRIEVER

import json
import neatlogs

with neatlogs.trace("retrieve_docs", kind="RETRIEVER") as span:
    span.set_attribute("neatlogs.retrieval.query", query)
    span.set_attribute("neatlogs.retrieval.top_k", top_k)
    docs = my_custom_retriever.search(query, k=top_k)
    span.set_attribute("neatlogs.retrieval.documents", json.dumps(docs))

Attribute	Type	Description
`neatlogs.retrieval.query`	`str`	Search query
`neatlogs.retrieval.top_k`	`int`	Number of results requested
`neatlogs.retrieval.documents`	`str` (JSON)	Retrieved documents as a JSON array

RERANKER

import json
import neatlogs

with neatlogs.trace("rerank", kind="RERANKER") as span:
    span.set_attribute("neatlogs.reranker.query", query)
    span.set_attribute("neatlogs.reranker.top_k", top_n)
    span.set_attribute("neatlogs.reranker.model_name", "cohere-rerank-v3")
    span.set_attribute("neatlogs.reranker.input_documents", json.dumps(docs))
    reranked = my_reranker.rerank(query, docs, top_n=top_n)
    span.set_attribute("neatlogs.reranker.output_documents", json.dumps(reranked))

Attribute	Type	Description
`neatlogs.reranker.query`	`str`	Original search query
`neatlogs.reranker.top_k`	`int`	Number of results to keep
`neatlogs.reranker.model_name`	`str`	Reranker model name (optional)
`neatlogs.reranker.input_documents`	`str` (JSON)	Documents before reranking
`neatlogs.reranker.output_documents`	`str` (JSON)	Documents after reranking

GUARDRAIL

import neatlogs

with neatlogs.trace("safety_check", kind="GUARDRAIL") as span:
    span.set_attribute("neatlogs.guardrail.input", content_to_check)
    passed, message = run_safety_check(content_to_check)
    span.set_attribute("neatlogs.guardrail.passed", passed)
    span.set_attribute("neatlogs.guardrail.output", message)

Attribute	Type	Description
`neatlogs.guardrail.input`	`str`	Content being checked
`neatlogs.guardrail.passed`	`bool`	Whether the check passed
`neatlogs.guardrail.output`	`str`	Validation result or failure reason

VECTOR_STORE

import neatlogs

with neatlogs.trace("index_documents", kind="VECTOR_STORE") as span:
    span.set_attribute("neatlogs.vectordb.index_name", "support_kb")
    span.set_attribute("neatlogs.vectordb.embedding_model", "text-embedding-3-small")
    span.set_attribute("neatlogs.vectordb.vector_dimension", 1536)
    my_custom_store.upsert(docs)

Attribute	Type	Description
`neatlogs.vectordb.index_name`	`str`	Collection or index name
`neatlogs.vectordb.embedding_model`	`str`	Embedding model used
`neatlogs.vectordb.vector_dimension`	`int`	Dimension of stored vectors
`neatlogs.vectordb.similarity_algorithm`	`str`	Distance metric (e.g., cosine)

Generic Custom Attributes

Any neatlogs.* attribute set on a span passes through to the backend. Use this for application-specific data you want to track:

with neatlogs.trace("my_step") as span:
    span.set_attribute("neatlogs.my_app.customer_tier", "enterprise")
    span.set_attribute("neatlogs.my_app.request_id", request_id)