Restructure manual tracing docs

[alexmojaki]

https://docs.pydantic.dev/logfire/guides/onboarding_checklist/add_manual_tracing/ currently has several issues as discussed with @Kludex and @dmontagu, including:

• A lot of long text about use cases that may put off users
• TODOs where screenshots should be
• Poor use of f-strings, e.g. logfire.span(f"Performing search: {search_query}", search_query=search_query, ...). This was written before f-string magic, but it doesn't make sense with or without.

Here is a proposed new outline for the page:

• Traces and spans
  • Simple code example: with logfire.span('This is a span'): logfire.info('This is an info log'); time.sleep(1)
  • Show how log is nested inside span in screenshot
  • Move https://docs.pydantic.dev/logfire/guides/first_steps/#opentelemetry-concepts here. I think it doesn't belong in 'First steps' where the user expects quick start instructions.
  • Explain that the trace is the root span of any tree, i.e. whenever there's no active span then opening a span starts a new trace.
  • Spans have a start and end and thus a duration. Show how to use this in SQL, e.g. filter by end_timestamp - start_timestamp > interval '1 second' in live view.
  • Logs are similar to spans but have no duration or children. Both logs and spans live in the records table with the same columns.
• Attributes
  • log.info('Hello', name='world')
  • attributes->>'name' = 'world'
  • span.set_attribute
  • logfire.info etc. have other keyword arguments starting with underscore. These are not private and users can use them. Attributes cannot start with underscore to keep the namespace reserved.
• Span name vs message
  • for name in ['Alice', 'Bob', 'Charlie']: log.info('Hello {name}', name=name)
  • span_name = 'Hello {name}' vs message like 'Hello %'
  • Span names should be low cardinality to group logs nicely
  • f-strings
  • _span_name kwarg
  • span.message writeable property
• @logfire.instrument
• Exceptions
  • Spans automatically record exceptions
  • logfire.exception
  • _exc_info kwarg
  • span.record_exception
• Log levels
  • logfire.info/error etc vs logfire.log
  • Spans are info by default
  • Filtering in the UI, e.g. level > level_num('info')
  • UI shows descendant levels
  • span.set_level
  • Unhandled exceptions in spans set the level to error

[Kludex]

A lot of long text about use cases that may put off users

Agree. We should reduce it.

TODOs where screenshots should be

Yes. We should AT least remove the TODOs.

Poor use of f-strings, e.g. logfire.span(f"Performing search: {search_query}", search_query=search_query, ...). This was written before f-string magic, but it doesn't make sense with or without.

We should just fix it - I don't care if we use the f-string or not, but the current one just doesn't make sense, as you mentioned.

Here is a proposed new outline for the page:

I agree with the outline.