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)