feat: export trace to a local file for quick debugging

[llin60]

Hi Langfuse team,

Thanks for this awesome SDK. I have been using it to test an application with agents involved. However, since the application is under rapid development phase, I made some changes to the exporter so that I can do quick local debugging without setting up the whole Langfuse services. I figured that these changes might be useful to someone else, so I submitted this PR.

This PR introduces an option to export OpenTelemetry traces to a local file, intended to improve the local development and debugging workflow.

Advantages:

• Easier Debugging: It allows developers to inspect raw trace data locally without needing a connection to a Langfuse backend, which is useful for debugging instrumentation.
• Offline Development: Enables validation of tracing implementations in environments with restricted or no network access.
• Simplified Analysis: Exported trace files can be easily shared, analyzed with custom scripts, or ingested into other tools.
• Cleaner Dev Environment: Prevents sending test or incomplete data to a production Langfuse project during development.

This feature is opt-in and does not alter the default behavior of the exporter.

To enable local file export, set the LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH environment variable. Ensure that the LANGFUSE_OTEL_TRACES_EXPORT_PATH variable is unset to avoid conflicts, which also protects the default exporter behavior. The local exporter is only effective when the LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH is set AND the LANGFUSE_OTEL_TRACES_EXPORT_PATH is unset.

# Set the local file path
export LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH="/path/to/my/traces.json"

# Unset the remote export path
unset LANGFUSE_OTEL_TRACES_EXPORT_PATH

---

Important

Adds local file export option for OpenTelemetry traces using a new environment variable and FileSpanExporter class.

• Behavior:
  • Adds local file export option for OpenTelemetry traces using LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH in environment_variables.py.
  • Introduces FileSpanExporter in span_processor.py to handle file-based trace export.
  • Local export is enabled only if LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH is set and LANGFUSE_OTEL_TRACES_EXPORT_PATH is unset.
• Classes:
  • FileSpanExporter in span_processor.py writes spans to a specified file in JSON format.
• Environment Variables:
  • Adds LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH to specify local file path for trace export in environment_variables.py.

^{This description was created by for 38937af. You can customize this summary. It will automatically update as commits are pushed.}

Disclaimer: Experimental PR review

Greptile Summary

This PR adds local file export for OpenTelemetry traces to support offline debugging. While the feature idea is valuable, the implementation has critical runtime errors that must be fixed before merging.

Critical Issues:

• ReadableSpan.to_json() method doesn't exist - will cause immediate runtime failure
• File opened in write mode ("w") overwrites all previous traces on each batch export, losing data

Suggested fixes:

• Use existing span_formatter utility or manually serialize span attributes
• Change file mode to append ("a") to accumulate traces across batches
• Add error handling for file operations

Confidence Score: 0/5

• This PR cannot be merged - it contains critical bugs that will cause runtime failures
• The FileSpanExporter calls a non-existent method (span.to_json()) which will immediately fail when the local export path is used. Additionally, the file overwrite issue will cause data loss. These are not edge cases but fundamental issues in the core functionality.
• langfuse/_client/span_processor.py requires immediate attention to fix critical bugs

Important Files Changed

Filename	Overview
langfuse/_client/environment_variables.py	adds new environment variable LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH with documentation
langfuse/_client/span_processor.py	adds FileSpanExporter class with critical bugs: calls non-existent to_json() method and overwrites file on each export

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Initialize LangfuseSpanProcessor] --> B{Check Environment Variables}
    B --> C{Is LANGFUSE_OTEL_TRACES_EXPORT_LOCAL_FILEPATH set?}
    C -->|Yes| D{Is LANGFUSE_OTEL_TRACES_EXPORT_PATH unset?}
    C -->|No| E[Use OTLPSpanExporter]
    D -->|Yes| F[Use FileSpanExporter]
    D -->|No| E
    F --> G[Export spans to local file]
    E --> H[Export spans to remote endpoint]
    G --> I[Write JSON to file per batch]
    H --> J[Send OTLP format via HTTP]

Loading

_{Last reviewed commit: 38937af}

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}

[CLAassistant]

All committers have signed the CLA.

[greptile-apps]

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

ReadableSpan objects don't have a to_json() method - this will fail at runtime. Consider using the existing span_formatter function from langfuse._client.utils or manually serialize the span attributes like it does.

[greptile-apps]

file opened in write mode ("w") which overwrites all previous spans each time export() is called - batch exports will lose data

Suggested change

	with open(self.filename, "w") as f:
	with open(self.filename, "a") as f: