> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

> Enrich events with context and details to facilitate analysis and debugging.

There are three ways to add metadata to logs and traces.

1. The first is to add metadata directly to Parea's completion method.
2. The second is to add metadata to the trace decorator.
3. Finally, for the Python SDK, if your trace has already been created, and you want to add dynamic metadata, you can use the trace\_insert helper function.

## Completion method

The completion method supports the following metadata fields:

* `trace_name` - default is 'LLM'
* `end_user_identifier` - This is a string representing any identifier for your end users such as an email address or user id.
* `metadata` - This is a serializable dictionary of key value pairs that you want added to the trace. ex: `{'git-hash': '1234abcd'}`
* `tags` - This is a list of strings that you want added to the trace. ex: `['tag1', 'tag2']`
* `target` - A string representing the ground truth answer you expect from the LLM

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    completion_with_metadata = Completion(
        trace_name="custom_trace_name",
        end_user_identifier="user_id_123",
        metadata={"git-hash": "1234awbcd"},
        tags=["tag1", "tag2"],
        target="ground_truth_answer",
    )
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    const completion: Completion = {
        trace_name: 'custom_trace_name',
        end_user_identifier: 'user_id_123',
        metadata: { 'git-hash': '1234awbcd' },
        tags: ['tag1', 'tag2'],
        target: 'ground_truth_answer',
    };
    ```
  </Tab>
</Tabs>

## Trace decorator

The trace decorator supports the same metadata fields as the completion method.

* `name` - default is the function's name
* `end_user_identifier`
* `metadata`
* `tags`
* `target`
* `deployment_id`
* `session_id` - A string representing a session id for the completion.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    @trace(
        name="custom_trace_name",
        end_user_identifier="user_id_123",
        metadata={"git-hash": "1234abcd"},
        tags=["tag1", "tag2"],
        target="ground_truth_answer",
        deployment_id="deployment_id"
        session_id="session_id"
    )
    def my_function():
        ...
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    const tracedFunc = trace('custom_trace_name', myFunction, {
        endUserIdentifier: 'user_id_123',
        metadata: { 'git-hash': '1234awbcd' },
        tags: ['tag1', 'tag2'],
        target: 'ground_truth_answer',
        deploymentId: 'deployment_id'
        sessionId: 'session_id'
    });
    ```
  </Tab>
</Tabs>

## Trace insert

Sometimes the metadata you want to add to a trace is based on something that happens within the function.
In this case you could use the `trace_insert()` helper function to add metadata to the trace.

`trace_insert` takes a dictionary of metadata field name to value.
The fields supported by trace\_insert are:

* `trace_name`
* `end_user_identifier`
* `metadata`
* `tags`
* `deployment_id`
* `session_id` - A string representing a session id for the completion.

<Tabs>
  <Tab title="Python">
    The new data will be added to the most recent trace.

    ```python theme={null}
    from parea import trace, trace_insert

    @trace
    def get_sections(chapter: Dict[str, str], model: str):
        # I want the trace name to be dynamic and based on the chapter dictionary passed in,
        # so I can use trace_insert helper method to add dynamic data
        trace_insert({"trace_name": f"Get {chapter['name']} Sections"})

        return client.chat.completions.create(
            model=model,
            temperature=0.7,
            messages=[
                {
                    "role": "user",
                    "content": f"Generate a section outline on {chapter['name']}, with description {chapter['description']}",
                }
            ],
        )
    ```
  </Tab>

  <Tab title="Typescript">
    You need to use the getCurrentTraceId() helper for the Typescript traceInsert helper method to know where to insert the  new data.

    ```typescript theme={null}
    import {getCurrentTraceId, trace, traceInsert} from "parea-ai";

    const getSections = trace('getSections', async (chapter: { name: string; description: string }, model: string) => {
        // I want the trace's metadata to be dynamic and contain the chapter name from the passed in object,
        // so I can use traceInsert helper method to add dynamic data
        traceInsert({metadata: {'chapterName': `Get ${chapter.name} Sections`}})
        return await openai.chat.completions.create({
            model, messages: [
                {
                    role: "user",
                    content: `Generate a section outline on ${chapter.name}, with description ${chapter.description}`,
                }
            ], temperature: 0.7
        });
    });
    ```
  </Tab>
</Tabs>

## What's Next

Now that we have added metadata to our traces, we add user feedback scores to our traces.