docs: conversation and user tracking via with_otel_attributes

[JulianPasquale]

Conversation tracking

This documents how to track conversations following the gen_ai otel semantic conventions.

To correlate multi-turn conversations, set gen_ai.conversation.id via with_otel_attributes, using a real conversation/session identifier from your application (a thread id, chat record id, etc.):

chat.with_otel_attributes("gen_ai.conversation.id" => chat.id)

[clarissalimab]

Hey @JulianPasquale, thank you for your contribution!

I'm hesitant to auto-populate the conversation ID with a random UUID, though, because the Otel GenAI convention recommends against it:

[4] gen_ai.conversation.id: Instrumentations SHOULD populate conversation id when they have an identifier
for the conversation readily available for a given operation, for example:

• when client framework being instrumented manages conversation history
  (see LlamaIndex chat store)
• when instrumenting GenAI client libraries that maintain conversation on the backend side
  (see AWS Bedrock agent sessions,
  OpenAI Assistant threads)

When no identifier for the conversation is available, instrumentations SHOULD NOT
populate conversation id. For example, a new UUID, a trace identifier, or a hash
of request content SHOULD NOT be used as a fallback value.

Application developers that manage conversation history MAY add conversation id to GenAI and other
spans or logs using custom span or log record processors or hooks provided by instrumentation
libraries.

I'm not sure whether RubyLLM::Chat provides some identifier that we could use (but I don't think so), and if not, I think we should avoid introducing that.

Your with_otel_attributes and user.* documentation is really helpful, though! Let me know if you can adjust it for us to merge it :)

[JulianPasquale]

Hey @clarissalimab, thanks for your review!

My bad I didn't notice the Otel recommendation. I have updated the PR to be a doc only change.

I'm not sure whether RubyLLM::Chat provides some identifier that we could use (but I don't think so), and if not, I think we should avoid introducing that.

I couldn't find anything useful, at least not in RubyLLM::Chat.
Maybe it will make sense to just track conversations when using the Chat model via the RubyLLM Rails integration, since the record primary key can be used as conversation identifier.

Let me know if there is something else you'd like me to change in this PR 🙂 .