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

# Logging Attributes

These are all the fields you can log to Athina.

<RequestExample>
  ```js
  {
      "language_model_id": "gpt-4",
      "prompt": [
          {
              "role": "system",
              "content": "Answer the following question using the information provided.\n ### INFORMATION ### Neil Armstrong landed on the moon in 1969.\n ### QUERY ###"
          },
          {
              "role": "user",
              "content": "Which spaceship was first to land on the moon?"
          }
      ],
      "response": "The Apollo 11 was the first spaceship to land on the moon.",
      "user_query": "Which spaceship was first to land on the moon?",
      "context": {
          "information": ["Neil Armstrong landed on the moon in 1969."]
      },
      "custom_attributes": {
          "company": "OpenAI",
          "links": ["https://openai.com"]
      },
      "prompt_tokens": 22,
      "completion_tokens": 9,
      "total_tokens": 31,
      "cost": 0.002,
      "response_time": 150,
      "prompt_slug": "qa_chatbot_response",
      "environment": "development",
      "customer_id": "xyz-123",
      "customer_user_id": "user-456",
      "session_id": "session-789",
      "external_reference_id": "ref-101112",
      "expected_response": "The Apollo 11 was the first spaceship to land on the moon.",
      "tools": [],
      "tool_calls": null,
      "functions": [],
      "function_call_response": {},
      "status_code": 500,
      "error": "Error message",
      "tags": ["qa", "chatbot"],
      "model_options": {
          "temperature": 0.7,
          "max_completion_tokens": 100,
          "top_p": 0.9,
          "extra_options": {
            "json_mode": true
          }
      }
  }


  ```
</RequestExample>

### Required Fields

<ParamField body="language_model_id" type="string" required>
  Identifier for the language model used for inference. This is just a string
  label, all models are supported.
</ParamField>

<ParamField body="prompt" type="string" required initialValue="Hello, how are you?" example="Hello, how are you?" defaultValue="Hello, how are you?" placeholder="Hello, how are you?">
  The prompt sent for inference. This can be either a `string` or the `messages`
  array sent to OpenAI. Note that in case of Tool message content can be either
  string or array.
</ParamField>

<ParamField body="response" type="string" required>
  The response from the LLM. This can be either a `string` or the `ChatCompletion` response object from OpenAI.
</ParamField>

### Eval Fields[](#eval-fields)

For most RAG [evals](api-reference/evals/preset-evals/rag), you must also log these fields:

<ParamField body="user_query" type="string">
  The user's query. For conversational applications, this is usually the user's last message.

  <Tip>Tip: Although this isn't required, this is **highly recommended** as several evals depend on this field.</Tip>
</ParamField>

<ParamField body="context" type="string | object">
  The retrieved context (if using RAG).

  <Tip>Tip: Although this isn't required, this is **highly recommended** as several evals depend on this field</Tip>
</ParamField>

***

### Latency

<ParamField body="response_time" type="int">
  The millisecond response time of the inference.
</ParamField>

***

### Status Code and Error

<ParamField body="status_code" type="int">
  The HTTP status code of the inference call made to the Llm provider. Eg., 200,
  500, etc.
</ParamField>

<ParamField body="error" type="string">
  The error message if the inference call failed. Eg "Internal Server Error"
  etc.
</ParamField>

***

### Token Usage and Cost

Athina will automatically calculate token usage and cost if the `language_model_id` is a known model.

However, you can also log the cost and token usage manually. These are used for analytics.

<ParamField body="prompt_tokens" type="int">
  The number of input (prompt) tokens used.
</ParamField>

<ParamField body="completion_tokens" type="int">
  The number of output (completion) tokens used.
</ParamField>

<ParamField body="total_tokens" type="int">
  The number of total tokens used. If this is not logged, we will simply add
  `prompt_tokens` and `completion_tokens`
</ParamField>

<ParamField body="cost" type="float">
  The cost of the inference. If this is not provided, we will automatically
  calculate the cost if the `language_model_id` is a known model.
</ParamField>

<Tip>
  Tip: If you log the entire OpenAI `ChatCompletion` response object to us,
  we'll automatically extract the token counts and cost.
</Tip>

***

### Segmentation Fields[](#segmentation-fields)

Optionally, you can also add the following fields for better segmentation on the dashboard

<ParamField body="prompt_slug" type="string">
  The identifier for the prompt used for inference. This is useful for
  segmenting inference calls by prompt.
</ParamField>

<ParamField body="environment" type="string">
  The environment your app is running in (ex: `production`, `staging`, etc).
  This is useful for segmenting inference calls by environment.
</ParamField>

<ParamField body="customer_id" type="string">
  The customer ID. This is useful for segmenting inference calls by customer.
</ParamField>

<ParamField body="customer_user_id" type="string">
  The end user ID. This is useful for segmenting inference calls by the end
  user.
</ParamField>

<ParamField body="tags" type="array[string]">
  A list of tags to associate with the log. This is useful for segmenting
  inference calls by tags.
</ParamField>

***

### Topics

<ParamField body="topic" type="string">
  For additional segmentation of data, you can log a topic string to associate
  with the log. This topic will then be used to filter logs on the dashboard,
  show comparisons, and granular analytics.
</ParamField>

***

### Logging Conversations

To group inferences into a conversation or chat session, just include the `session_id` field.

<ParamField body="session_id" type="string">
  The session or conversation ID. This is used for grouping different inferences
  into a conversation or chain. [Read
  more](faqs/logging/how-can-i-log-conversations)
</ParamField>

***

### Logging Custom Attributes

You can log any custom attributes to Athina to be shown as metadata.

<ParamField body="external_reference_id" type="string">
  An external reference ID for the inference. This can be used to update the
  logs later. [Read
  more](/api-reference/logging/updates/update-logs-by-external-reference-id).
</ParamField>

<ParamField body="custom_attributes" type="object">
  Additional metadata to add to this log.
</ParamField>

Optionally, you can also log custom attributes with your prompt. You can pass attribute name and attribute value as key-value pair in the `custom_attributes` object.

Note:- A prompt run cannot have duplicate attribute names

### Ground Truth

If you have ground truth responses, you can log them here. Ground truth responses are required for some evals like [Answer Similarity](api-reference/evals/preset-evals/grounded-evals#answer_similarity)

<ParamField body="expected_response" type="string">
  Ground-truth or reference response.
</ParamField>

### Tools

For tools, you may log the following fields:

<ParamField body="tools" type="array[object]">
  Lists tools (defined as JSON) the model may call. This should be an array of
  tool definitions.
</ParamField>

<ParamField body="tool_choice" type="string">
  Controls the model's tool calls. This can be `none`, `auto`, or a specific
  tool name.
</ParamField>

<CodeGroup>
  ```json tool_call_example
  {
    "language_model_id": "gpt-4",
    "prompt": [
      {
        "role": "user",
        "content": "How hot is it today in New York?"
      }
    ],
    "response": {
      "id": "chatcmpl-AAxPVOxthxY6I8infZcR2LUGPgrY",
      "choices": [
        {
          "finish_reason": "tool_calls",
          "index": 0,
          "logprobs": null,
          "message": {
            "content": null,
            "refusal": null,
            "role": "assistant",
            "function_call": null,
            "tool_calls": [
              {
                "id": "call_ngUsEYbYpmPJF1EJusi2UjU",
                "function": {
                  "arguments": "{\n  \"location\": \"New York\",\n  \"format\": \"celsius\"\n}",
                  "name": "get_current_weather"
                },
                "type": "function"
              }
            ]
          }
        }
      ],
      "created": 1727175017,
      "model": "gpt-4-0613",
      "object": "chat.completion",
      "service_tier": null,
      "system_fingerprint": null,
      "usage": {
        "completion_tokens": 25,
        "prompt_tokens": 93,
        "total_tokens": 118,
        "completion_tokens_details": {
          "reasoning_tokens": 0
        }
      }
    },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "format": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "The temperature unit to use. Infer this from the users location."
              }
            },
            "required": ["location", "format"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }
  ```
</CodeGroup>

### Function Calling

For function calling, you may also log the following fields:

<ParamField body="functions" type="array[object]">
  Function call request
</ParamField>

<ParamField body="function_call_response" type="object (JSON)">
  Function call response
</ParamField>

<Tip>
  Tip: To avoid adding any latency to your application, log your inference as a
  fire-and-forget request.
</Tip>

### Feedback

Learn how to update logs [by ID](/api-reference/logging/updates/update-logs-by-id) or [by external reference ID](/api-reference/logging/updates/update-logs-by-id).

<ParamField body="user_feedback" type="number">
  A number representing the end user's feedback. For example, `1` for positive
  feedback, `-1` for negative feedback.
</ParamField>

<ParamField body="user_feedback_comment" type="string">
  A comment from the end user about the response.
</ParamField>

<ParamField body="grader_feedback" type="number">
  A number representing the grader's feedback. For example, `1` for positive
  feedback, `-1` for negative feedback.
</ParamField>

### Model Options

Log model options to get insights into how model behavior affects your end users.
The `model_options` key is optional but required to reproduce llm requests.

<ParamField body="model_options.temperature" type="number">
  The model temperature, usually between 0.0 and 2.0.
</ParamField>

<ParamField body="model_options.max_completion_tokens" type="number">
  The maximum number of tokens for the model to generate.
</ParamField>

<ParamField body="model_options.stop" type="string | array[string]">
  The stop sequence(s) for the model to use. This can be a single string or an
  array of strings that indicate where the model should stop generating further
  tokens.
</ParamField>

<ParamField body="model_options.top_p" type="number">
  Uses nucleus sampling for choosing tokens.
</ParamField>

<ParamField body="model_options.extra_options" type="object">
  A object of key value pairs. Log any key value pairs you want that may help
  with recreating this llm request.
</ParamField>