Add reference docs

[Huw-man]

Subtrace Knowledge Gap Analysis

1. TLS/Certificate Authority Issues

Source - Discord Discussion with Feynman

Feynman — 11/15/24, 5:45 PM
OK it didn't like the init shell script
when i ran with the binary i am getting cert errors

# SUBTRACE_TOKEN=subt_doZlLUqp8O9xYaYfSE0c0z4IsVhx5KLav24G0zVUhxb subtrace run -- /app/bin/dreamcatcher start

[notice] TLS :client: In state :wait_cert_cr at ssl_handshake.erl:2138 generated CLIENT ALERT: Fatal - Unknown CA

Documentation Gaps

• troubleshooting-guide.md: Requires a TLS specific section
• run-guide.md: Needs expanded documentation on -tls=false flag and certificate handling
• quickstart.md: Could mention potential TLS issues earlier

2. Path/Binary Installation Problems

Source - Discord Discussion with cdxker

cdxker — 11/12/24, 2:24 PM
Having an issue with the integration. 
https://github.com/devflowinc/trieve/pull/2733/files

docker run -it trieve/server:test-subtrace 

[cdxker@gibraltar ~]$ docker run -it trieve/server:test-subtrace
docker: Error response from daemon: failed to create task for container: failed to create shim task: OCI runtime create failed: runc create failed: unable
to start container process: error during container init: exec: "subtrace": executable file not found in $PATH: unknown.

Documentation Gaps

• quickstart.mdx: Should include Docker-specific installation steps
• troubleshooting-guide.mdx: Needs expanded Docker troubleshooting section
• run-guide.mdx: Should include PATH setup instructions

3. Authentication and Token Management

Source - Discord Discussion with Feynman

Feynman — 11/15/24, 1:40 PM
where do i get a non-worker token?

sachin — 11/15/24, 1:46 PM
Go to the dashboard (https://subtrace.dev/dashboard/), click on Tokens in the left pane -> Create tracer token

Related Issue

• Issue #15: "add subcommand to test the validity of the CLI API token for auth"

Documentation Gaps

• worker-guide.mdx: Needs clear explanation of where to get worker and tracer tokens
• quickstart.mdx: Should explain different token types
• troubleshooting-guide.mdx: Add token validation troubleshooting

4. Proxy Configuration

Source - Discord Discussion with skeptrune

skeptrune - trieve.ai — 11/22/24, 6:08 PM
regex is actually genius for configuring which requests to track

adtac (subtrace) — 11/22/24, 6:10 PM
we have more! we want to make it easy to redact particular HTTP header values using the same config file in a declarative way

Related Issue

• Issue #68: "proxy: allow users to opt into storing a short, truncated fingerprint of credentials"

Documentation Gaps

• proxy-guide.mdx: Needs expanded configuration examples
• run-guide.mdx: Should document interaction with proxy settings

5. Performance Impact & Binary Size

Source - Discord Announcement from adtac

adtac (subtrace) — 12/2/24, 10:50 AM
Latency Benchmarks

We've added a section to our docs measuring the overhead of adding Subtrace to your backend. Even under extreme load, Subtrace adds well under 1 millisecond in latency; under more typical workloads, expect less than 0.1ms in added latency. For reference, the latency between two machines in the same AWS datacenter is usually 4-10 milliseconds!

While this is already imperceptible to the end user in nearly every use-case, we have a bunch of low hanging fruits to optimize in the future. Stay tuned! 

Related Issues

• Issue #46: "worker: replace text/template in templated migrations to reduce binary size"
• Issue #79: "proxy: truncate payload in HAR beyond a limit"

Documentation Gaps

• run-guide.mdx: Should include performance benchmarks
• worker-guide.mdx: Need binary size optimization guidance
• troubleshooting-guide.mdx: Add performance tuning section

6. HTTP/2 Support Documentation

Source - GitHub Issue

• Issue #4: "tracer: add back HTTP/2 support"

Documentation Gaps

• proxy-guide.mdx: Needs to clarify HTTP/2 support status
• run-guide.mdx: Should document protocol support matrix
• troubleshooting-guide.mdx: Add protocol-specific troubleshooting

7. Worker Setup and Management

Source - GitHub Issue

• Issue #13: "worker: use either the clickhouse HTTP port or the native protocol port"

Documentation Gaps

• worker-guide.mdx: Needs expanded port configuration section
• quickstart.mdx: Should include basic worker setup troubleshooting
• troubleshooting-guide.mdx: Add worker-specific issues

Recommendations

1. Create New Documentation Sections

   • Add a reference for existing subtrace commands
   • "Common Deployment Patterns" as a new guide
   • "Security Best Practices" standalone guide
   • "Protocol Support Matrix" as a new section
   • "Performance Tuning Guide" standalone document

2. Expand Existing Documentation

   • Add more Docker examples to troubleshooting-guide.mdx
   • Expand token management in the quickstart and subtrace woker guides
   • Add more configuration examples to proxy-guide.mdx
   • Include error message catalog in troubleshooting-guide.mdx

3. Documentation Structure Improvements

   • Add cross-references between guides
   • Include a glossary of terms
   • Create a decision tree for common issues
   • Add more real-world examples

4. New Tutorials Needed

   • Token management tutorial
   • Performance optimization guide
   • Protocol support guide