Skip to main content
Version: 2.0.0

Metadata

You can attach custom context (we call this metadata) to your pipeline runs. If you want to associate a URL to an external service or a prompt variant to the run, you can use metadata to tag your generations.

Types​

The value object for each metadata value is a union type. We only support two value types at this time. We will add more upon request.

"type": "url"​

If specified as a URL, you must specify url and text key/value pairs.

json
{
    "type": "url",
    "url": "https://external-service.example.com",
    "text": "External service"  
}

"type": "string"​

If specified as a string, you must specify a value key/value pair.

json
{
    "type": "string",
    "value": "MzY0MzQ0"
}
Malformed metadata

If your metadata is not properly formatted with the specified type, our API will reject your request.

Usage​

Advanced example for generation​

You can associate metadata with an entire generation by specifying the metadata key in .start() function.

typescript
import { Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
const GIT_SHA = "63ce36deceeb28da94f7f8176166f9f1f399134d";
 
const plugin = await initPlugin({
  apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
  slug: "advanced-pipeline",
  plugins: {
    openai: plugin,
  },
});
 
const runner = pipeline.start({
  metadata: {
    // We support multiple key/value pairs within the metadata object
    externalServiceUrl: {
      // Every metadata object must have a "type" key
      type: "url",
      url: "https://external-service.example.com",
      text: "External service"
    },
    gitSha: {
      type: "string",
      value: GIT_SHA
    }
  }
});
 
const openai = runner.openai;
 
const chatCompletionResponse = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
  model: "gpt-3.5-turbo",
  stream: true
});
 
await runner.submit()

Advanced example on step​

You can also add metadata to the run by using the context object for a particular step.

typescript
import { Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
const GIT_SHA = "63ce36deceeb28da94f7f8176166f9f1f399134d";
 
const plugin = await initPlugin({
  apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
  slug: "advanced-pipeline",
  plugins: {
    openai: plugin,
  },
});
 
const runner = pipeline.start();
 
const openai = runner.openai;
 
const chatCompletionResponse = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
  model: "gpt-3.5-turbo",
  stream: true,
  
  gentrace: {
    metadata: {
      // We support multiple metadata keys within the metadata object
      externalServiceUrl: {
        // Every metadata object must have a "type" key
        type: "url",
        url: "https://external-service.example.com",
        text: "External service"
      },
      gitSha: {
        type: "string",
        value: GIT_SHA
      }
    }
  }
});
 
await runner.submit();

Behavior​

All metadata is scoped to a pipeline run. If you're using the advanced SDK and have multiple interim steps in your pipeline, any metadata that you associate with a step is associated directly with the pipeline run, not the step.

Let's say you have the following pipeline.

typescript
import { Pipeline } from "@gentrace/core";
import { initPlugin } from "@gentrace/openai";
 
const GIT_SHA = "63ce36deceeb28da94f7f8176166f9f1f399134d";
 
const plugin = await initPlugin({
  apiKey: process.env.OPENAI_KEY,
});
 
const pipeline = new Pipeline({
  slug: "advanced-pipeline",
  plugins: {
    openai: plugin,
  },
});
 
const runner = pipeline.start({
  // Assign metadata upon pipeline instantiation
  metadata: {
    gitSha: {
      type: "string",
      value: GIT_SHA
    }
  }
});
 
const openai = runner.openai;
 
const chatCompletionResponse = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
  model: "gpt-3.5-turbo",
  stream: true,
  
  gentrace: {
    // Create additional metadata when you're adding steps to your pipeline
    metadata: {
      // We support multiple metadata keys within the metadata object
      externalServiceUrl: {
        // Every metadata object must have a "type" key
        type: "url",
        url: "https://external-service.example.com",
        text: "External service"
      }
    }
  }
});

Both items will render in the runs page in the Gentrace UI similar to below.

Metadata keys will overwrite

When defining a metadata key with the same identifier in a pipeline run, please note that only the latest write will be applied to the metadata for the entire run.

typescript
// Omit SDK and pipeline run initialization
 
const first = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Hello! What's the capital of Maine?" }],
  model: "gpt-3.5-turbo",
  stream: true,
  gentrace: {
    metadata: {
      promptId: {
        type: "string",
        value: "MzY0MzQ0"
      }
    }
  }
});
 
// ...
 
const second = await openai.chat.completions.create({
  messages: [{ role: "user", content: "Hello! What's the capital of Georgia" }],
  model: "gpt-3.5-turbo",
  stream: true,
  gentrace: {
    // 🚧 This overwrites the first instantiation
    metadata: {
      promptId: {
        type: "string",
        value: "SGVsbG8g"
      }
    }
  }
});