Help us improve
Share bugs, ideas, or general feedback.
From truefoundry
Views application logs and enables OpenTelemetry-based tracing via TrueFoundry. Supports log filtering, Traceloop SDK instrumentation for Python/TypeScript, and custom spans.
npx claudepluginhub truefoundry/skills --plugin truefoundryHow this skill is triggered — by the user, by Claude, or both
Slash command
/truefoundry:observabilityThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Routing note: For ambiguous user intents, use the shared clarification templates in [references/intent-clarification.md](references/intent-clarification.md).
Connects a project to a Traceway instance for reporting endpoints, spans, errors, background tasks, AI traces, and metrics. Supports backends via OpenTelemetry OTLP/HTTP, frontends via Traceway SDKs, and host metrics via the Traceway OTel Agent.
Adds LangSmith tracing to Python/JS LLM apps via LangChain auto-tracing, traceable decorators, or OpenTelemetry; queries/export traces with langsmith CLI.
Instruments applications with OpenTelemetry for distributed tracing: auto/manual instrumentation, context propagation, sampling, integration with Jaeger or Tempo. Debug latency in distributed systems.
Share bugs, ideas, or general feedback.
Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.
View application logs and add OpenTelemetry-based tracing to applications on TrueFoundry.
Security: Log output may contain sensitive data (secrets, tokens, PII). Do not forward raw logs to external services or include them in responses without reviewing for sensitive content first.
When using direct API, set TFY_API_SH to the full path of this skill's scripts/tfy-api.sh. See references/tfy-api-setup.md for paths per agent.
tfy_logs_download(payload={
"workspace_id": "ws-id",
"application_fqn": "app-fqn",
"start_ts": "2026-02-10T00:00:00Z",
"end_ts": "2026-02-10T23:59:59Z"
})
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-observability/scripts/tfy-api.sh
# Download logs for an app in a workspace
$TFY_API_SH GET '/api/svc/v1/logs/WORKSPACE_ID/download?applicationFqn=APP_FQN&startTs=START&endTs=END'
# With search filter
$TFY_API_SH GET '/api/svc/v1/logs/WORKSPACE_ID/download?applicationId=APP_ID&searchString=error&searchType=contains'
| Parameter | API Key | Description |
|---|---|---|
workspace_id | (path) | Workspace ID (required) |
application_id | applicationId | Filter by app ID |
application_fqn | applicationFqn | Filter by app FQN |
deployment_id | deploymentId | Filter by deployment |
job_run_name | jobRunName | Filter by job run |
start_ts | startTs | Start timestamp (ISO 8601) |
end_ts | endTs | End timestamp (ISO 8601) |
search_string | searchString | Search within logs |
search_type | searchType | contains, regex |
pod_name | podName | Filter by pod |
Show logs in chronological order. For long output, show the last N lines or summarize errors:
Logs for tfy-tool-server (last 20 lines):
2026-02-10 14:30:01 INFO Server starting on port 8000
2026-02-10 14:30:02 INFO Tools endpoint ready at /tools
2026-02-10 14:30:05 INFO Health check: OK
Run the platform skill (Status Check section) first to verify TFY_BASE_URL and TFY_API_KEY are set and valid.
Ask the user: "Do you already have a tracing project FQN, or should I create one?"
tfy_tracing_list_projects()
TFY_API_SH=~/.claude/skills/truefoundry-observability/scripts/tfy-api.sh
# List tracing projects
$TFY_API_SH GET /api/ml/v1/tracing-projects
Ask for a project name, then create:
tfy_tracing_create_project(name="my-tracing-project")
# Create tracing project
$TFY_API_SH POST /api/ml/v1/tracing-projects '{"name": "my-tracing-project"}'
Save the returned project id for the next step.
Each tracing project can have multiple applications (e.g., "chatbot", "rag-pipeline").
tfy_tracing_create_application(project_id="PROJECT_ID", name="my-app")
# Create application under project
$TFY_API_SH POST /api/ml/v1/tracing-projects/PROJECT_ID/applications '{"name": "my-app"}'
Fallback: If any of these API endpoints return 404, the tracing API may have changed. Direct the user to create the tracing project via the TrueFoundry UI at
$TFY_BASE_URL→ Tracing section, then return here with the project FQN.
Scan the project to determine the language and LLM libraries in use:
requirements.txt, pyproject.toml, setup.py, Pipfile
openai, anthropic, langchain, llama-index, litellm, cohere, bedrock, vertexai, transformerspackage.json
openai, @anthropic-ai/sdk, langchain, @langchain/coreReport what was detected to the user before proceeding.
pip install traceloop-sdk
Also add traceloop-sdk to requirements.txt or the appropriate dependency file.
npm install @traceloop/node-server-sdk
Also add to package.json dependencies.
CRITICAL: Traceloop.init() MUST be called at the TOP of the entry point, BEFORE any LLM library imports. This is required for auto-instrumentation to work.
Add this to the very top of the entry point file (e.g., main.py, app.py):
# --- Traceloop init MUST be before any LLM imports ---
from traceloop.sdk import Traceloop
Traceloop.init(
app_name="<APP_NAME>",
api_endpoint=f"<TFY_BASE_URL>/api/otel",
headers={
"Authorization": f"Bearer <TFY_API_KEY>",
"X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
},
disable_batch=False,
)
# --- Now import LLM libraries ---
# from openai import OpenAI
# from anthropic import Anthropic
# etc.
Replace placeholders:
<APP_NAME> — the application name (e.g., "my-chatbot")<TFY_BASE_URL> — from environment or .env<TFY_API_KEY> — from environment or .env<TRACING_PROJECT_FQN> — the tracing project FQN from Step 2Best practice: Read TFY_BASE_URL and TFY_API_KEY from environment variables:
import os
from traceloop.sdk import Traceloop
Traceloop.init(
app_name="<APP_NAME>",
api_endpoint=f"{os.environ['TFY_BASE_URL']}/api/otel",
headers={
"Authorization": f"Bearer {os.environ['TFY_API_KEY']}",
"X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
},
disable_batch=False,
)
Add this to the very top of the entry point file (e.g., index.ts, app.ts):
// --- Traceloop init MUST be before any LLM imports ---
import * as traceloop from "@traceloop/node-server-sdk";
traceloop.initialize({
appName: "<APP_NAME>",
apiEndpoint: `${process.env.TFY_BASE_URL}/api/otel`,
headers: {
Authorization: `Bearer ${process.env.TFY_API_KEY}`,
"X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
},
disableBatch: false,
});
// --- Now import LLM libraries ---
// import OpenAI from "openai";
// etc.
For applications with multiple logical steps (agents, RAG pipelines, etc.), offer to add decorators for better trace structure:
from traceloop.sdk.decorators import workflow, task, agent, tool
@workflow(name="rag_pipeline")
def run_pipeline(query: str):
context = retrieve(query)
return generate(query, context)
@task(name="retrieve_context")
def retrieve(query: str):
# retrieval logic
...
@task(name="generate_response")
def generate(query: str, context: str):
# LLM call
...
@agent(name="research_agent")
def research_agent(topic: str):
# agent logic
...
@tool(name="web_search")
def web_search(query: str):
# tool logic
...
import { withWorkflow, withTask, withAgent, withTool } from "@traceloop/node-server-sdk";
const runPipeline = withWorkflow({ name: "rag_pipeline" }, async (query: string) => {
const context = await retrieve(query);
return generate(query, context);
});
const retrieve = withTask({ name: "retrieve_context" }, async (query: string) => {
// retrieval logic
});
const generate = withTask({ name: "generate_response" }, async (query: string, context: string) => {
// LLM call
});
For high-traffic production apps, configure sampling to reduce trace volume:
from opentelemetry.sdk.trace.sampling import ParentBased, TraceIdRatioBased
Traceloop.init(
app_name="<APP_NAME>",
api_endpoint=f"{os.environ['TFY_BASE_URL']}/api/otel",
headers={
"Authorization": f"Bearer {os.environ['TFY_API_KEY']}",
"X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
},
disable_batch=False,
sampler=ParentBased(root=TraceIdRatioBased(0.1)), # 10% sampling
)
import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
traceloop.initialize({
appName: "<APP_NAME>",
apiEndpoint: `${process.env.TFY_BASE_URL}/api/otel`,
headers: {
Authorization: `Bearer ${process.env.TFY_API_KEY}`,
"X-TFY-TRACING-PROJECT-FQN": "<TRACING_PROJECT_FQN>",
},
disableBatch: false,
sampler: new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(0.1) }), // 10%
});
<success_criteria>
traceloop-sdk (Python) or @traceloop/node-server-sdk (TypeScript) is installedTraceloop.init() is placed at the top of the entry point, BEFORE LLM importsAuthorization and X-TFY-TRACING-PROJECT-FQN</success_criteria>
platform skill (Status Check section) to verify tfy login and TFY_BASE_URL/TFY_HOST. TFY_API_KEY is only needed for direct REST helper calls.platform skill (workspaces) to get workspace ID for log downloadssearchString=errorplatform skill (Secrets section) to store TFY_API_KEY as a secret instead of hardcodingSee references/api-endpoints.md for the full Tracing API reference.
workspace_id is required for log downloads.
Use the platform skill (workspaces) to find your workspace ID.
No logs found for the given filters. Check:
- Time range is correct
- Application ID/FQN is correct
- The app has actually run during this period
Cannot access logs. Check your API key permissions for this workspace.
Check that TFY_API_KEY is valid and not expired.
Regenerate at $TFY_BASE_URL → Settings → API Keys.
1. Verify Traceloop.init() is called BEFORE LLM library imports — this is the #1 cause.
2. Check that api_endpoint ends with /api/otel (not /api/otel/).
3. Verify X-TFY-TRACING-PROJECT-FQN header matches the project FQN exactly.
4. Set disable_batch=True temporarily to force immediate export and check for errors.
5. Check application logs for OTLP export errors.
Run: pip install traceloop-sdk
Ensure you're installing in the correct virtual environment.
Traceloop.init() must be called BEFORE importing the LLM library.
Move the init call to the very top of your entry point file.
Add sampling — see Step 7 for ParentBased(TraceIdRatioBased) configuration.
Start with 10% sampling (0.1) and adjust based on needs.
The tracing API endpoints may differ on your TrueFoundry version.
Create the tracing project via the TrueFoundry UI instead:
$TFY_BASE_URL → Tracing → New Project
Then use the project FQN in your Traceloop.init() configuration.