第九章：观测篇

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-model-openai</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-model-chat-client</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-autoconfigure-model-tool</artifactId>
    </dependency>

    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-vector-store</artifactId>
    </dependency>

</dependencies>

server:
  port: 8080

spring:
  application:
    name: observability

  ai:
    openai:
      api-key: ${DASHSCOPEAPIKEY}
      base-url: https://dashscope.aliyuncs.com/compatible-mode
      chat:
        options:
          model: qwen-max
      embedding:
        options:
          model: text-embedding-v1

package com.spring.ai.tutorial.observability.config;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationHandler;
import io.micrometer.observation.ObservationRegistry;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClientRequest;
import org.springframework.ai.chat.client.advisor.api.Advisor;
import org.springframework.ai.chat.client.observation.ChatClientObservationContext;
import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.observation.ChatModelObservationContext;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.embedding.observation.EmbeddingModelObservationContext;
import org.springframework.ai.observation.AiOperationMetadata;
import org.springframework.ai.tool.definition.ToolDefinition;
import org.springframework.ai.tool.observation.ToolCallingObservationContext;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.lang.reflect.ParameterizedType;
import java.lang.reflect.Type;
import java.util.List;

@Configuration
public class ObservationConfiguration {

    private static final Logger logger = LoggerFactory.getLogger(ObservationConfiguration.class);

    @Bean
    @ConditionalOnMissingBean(name = "observationRegistry")
    public ObservationRegistry observationRegistry(
            ObjectProvider<ObservationHandler<?>> observationHandlerObjectProvider) {
        ObservationRegistry observationRegistry = ObservationRegistry.create();
        ObservationRegistry.ObservationConfig observationConfig = observationRegistry.observationConfig();
        observationHandlerObjectProvider.orderedStream().forEach(handler -> {
            Type[] genericInterfaces = handler.getClass().getGenericInterfaces();
            for (Type type : genericInterfaces) {
                if (type instanceof ParameterizedType parameterizedType
                        && parameterizedType.getRawType() instanceof Class<?> clazz
                        && ObservationHandler.class.isAssignableFrom(clazz)) {

                    Type actualTypeArgument = parameterizedType.getActualTypeArguments()[0];
                    logger.info("load observation handler, supports context type: {}", actualTypeArgument);
                }
            }

            // 将handler添加到observationRegistry中
            observationConfig.observationHandler(handler);
        });
        return observationRegistry;
    }

    /**
     * 监听chat client调用
     */
    @Bean
    ObservationHandler<ChatClientObservationContext> chatClientObservationContextObservationHandler() {
        logger.info("ChatClientObservation start");
        return new ObservationHandler<>() {

            @Override
            public boolean supportsContext(Observation.Context context) {
                return context instanceof ChatClientObservationContext;
            }

            @Override
            public void onStart(ChatClientObservationContext context) {
                ChatClientRequest request = context.getRequest();
                List<? extends Advisor> advisors = context.getAdvisors();
                boolean stream = context.isStream();
                logger.info("💬ChatClientObservation start: ChatClientRequest : {}, Advisors : {}, stream : {}",
                        request, advisors, stream);
            }

            @Override
            public void onStop(ChatClientObservationContext context) {
                ObservationHandler.super.onStop(context);
            }
        };
    }

    /**
     * 监听chat model调用
     */
    @Bean
    ObservationHandler<ChatModelObservationContext> chatModelObservationContextObservationHandler() {
        logger.info("ChatModelObservation start");
        return new ObservationHandler<>() {

            @Override
            public boolean supportsContext(Observation.Context context) {
                return context instanceof ChatModelObservationContext;
            }

            @Override
            public void onStart(ChatModelObservationContext context) {
                AiOperationMetadata operationMetadata = context.getOperationMetadata();
                Prompt request = context.getRequest();
                logger.info("🤖ChatModelObservation start: AiOperationMetadata : {}",
                        operationMetadata);
                logger.info("🤖ChatModelObservation start: Prompt : {}",
                        request);
            }

            @Override
            public void onStop(ChatModelObservationContext context) {
                ChatResponse response = context.getResponse();
                logger.info("🤖ChatModelObservation start: ChatResponse : {}",
                        response);
            }
        };
    }

    /**
     * 监听工具调用
     */
    @Bean
    public ObservationHandler<ToolCallingObservationContext> toolCallingObservationContextObservationHandler() {
        logger.info("ToolCallingObservation start");
        return new ObservationHandler<>() {
            @Override
            public boolean supportsContext(Observation.Context context) {
                return context instanceof ToolCallingObservationContext;
            }

            @Override
            public void onStart(ToolCallingObservationContext context) {
                ToolDefinition toolDefinition = context.getToolDefinition();
                logger.info("🔨ToolCalling start: {} - {}", toolDefinition.name(), context.getToolCallArguments());
            }

            @Override
            public void onStop(ToolCallingObservationContext context) {
                ToolDefinition toolDefinition = context.getToolDefinition();
                logger.info("✅ToolCalling done: {} - {}", toolDefinition.name(), context.getToolCallResult());
            }
        };
    }

    /**
     * 监听embedding model调用
     */
    @Bean
    public ObservationHandler<EmbeddingModelObservationContext> embeddingModelObservationContextObservationHandler() {
        logger.info("EmbeddingModelObservation start");
        return new ObservationHandler<>() {
            @Override
            public boolean supportsContext(Observation.Context context) {
                return context instanceof EmbeddingModelObservationContext;
            }

            @Override
            public void onStart(EmbeddingModelObservationContext context) {
                logger.info("📚EmbeddingModelObservation start: {} - {}", context.getOperationMetadata().operationType(),
                        context.getOperationMetadata().provider());
            }
        };
    }


}

package com.spring.ai.tutorial.observability.controller;

import com.spring.ai.tutorial.observability.tools.TimeTools;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder
                .build();
    }

    @GetMapping("/call")
    public String call(@RequestParam(value = "query", defaultValue = "你好，很高兴认识你，能简单介绍一下自己吗？")String query) {
        return chatClient.prompt(query).call().content();
    }

    /**
     * 调用工具版 - method
     */
    @GetMapping("/call/tool-method")
    public String callToolMethod(@RequestParam(value = "query", defaultValue = "请告诉我现在北京时间几点了") String query) {
        return chatClient.prompt(query).tools(new TimeTools()).call().content();
    }
}

package com.spring.ai.tutorial.observability.controller;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.document.Document;
import org.springframework.ai.embedding.EmbeddingModel;
import org.springframework.ai.vectorstore.SearchRequest;
import org.springframework.ai.vectorstore.SimpleVectorStore;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/vector/simple")
public class VectorSimpleController {
    private static final Logger logger = LoggerFactory.getLogger(VectorSimpleController.class);

    private final SimpleVectorStore simpleVectorStore;

    public VectorSimpleController(EmbeddingModel embeddingModel) {
        this.simpleVectorStore = SimpleVectorStore
                .builder(embeddingModel).build();
    }

    @GetMapping("/add")
    public void add() {
        logger.info("start add data");

        HashMap<String, Object> map = new HashMap<>();
        map.put("year", 2025);
        map.put("name", "yingzi");
        List<Document> documents = List.of(
                new Document("The World is Big and Salvation Lurks Around the Corner"),
                new Document("You walk forward facing the past and you turn back toward the future.", Map.of("year", 2024)),
                new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", map),
                new Document("1", "test content", map));
        simpleVectorStore.add(documents);
    }

    @GetMapping("/search")
    public List<Document> search() {
        logger.info("start search data");
        return simpleVectorStore.similaritySearch(SearchRequest
                .builder()
                .query("Spring")
                .topK(2)
                .build());
    }

}

package io.micrometer.observation;

import io.micrometer.common.KeyValues;
import io.micrometer.common.lang.Nullable;

public interface ObservationConvention<T extends Observation.Context> extends KeyValuesConvention {
    ObservationConvention<Observation.Context> EMPTY = (context) -> false;

    default KeyValues getLowCardinalityKeyValues(T context) {
        return KeyValues.empty();
    }

    default KeyValues getHighCardinalityKeyValues(T context) {
        return KeyValues.empty();
    }

    boolean supportsContext(Observation.Context var1);

    @Nullable
    default String getName() {
        return null;
    }

    @Nullable
    default String getContextualName(T context) {
        return null;
    }
}

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-autoconfigure-model-chat-observation</artifactId>
</dependency>

<dependency>
  <groupId>org.springframework.ai</groupId>
  <artifactId>spring-ai-model</artifactId>
</dependency>

package org.springframework.ai.model.chat.observation.autoconfigure;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("spring.ai.chat.observations")
public class ChatObservationProperties {
    public static final String CONFIGPREFIX = "spring.ai.chat.observations";
    private boolean logCompletion = false;
    private boolean logPrompt = false;
    private boolean includeErrorLogging = false;

    public boolean isLogCompletion() {
        return this.logCompletion;
    }

    public void setLogCompletion(boolean logCompletion) {
        this.logCompletion = logCompletion;
    }

    public boolean isLogPrompt() {
        return this.logPrompt;
    }

    public void setLogPrompt(boolean logPrompt) {
        this.logPrompt = logPrompt;
    }

    public boolean isIncludeErrorLogging() {
        return this.includeErrorLogging;
    }

    public void setIncludeErrorLogging(boolean includeErrorLogging) {
        this.includeErrorLogging = includeErrorLogging;
    }
}

package org.springframework.ai.model.chat.observation.autoconfigure;

import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.tracing.Tracer;
import java.util.List;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.advisor.observation.AdvisorObservationContext;
import org.springframework.ai.chat.client.observation.ChatClientObservationContext;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.observation.ChatModelCompletionObservationHandler;
import org.springframework.ai.chat.observation.ChatModelMeterObservationHandler;
import org.springframework.ai.chat.observation.ChatModelObservationContext;
import org.springframework.ai.chat.observation.ChatModelPromptContentObservationHandler;
import org.springframework.ai.embedding.observation.EmbeddingModelObservationContext;
import org.springframework.ai.image.observation.ImageModelObservationContext;
import org.springframework.ai.model.observation.ErrorLoggingObservationHandler;
import org.springframework.ai.observation.TracingAwareLoggingObservationHandler;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@AutoConfiguration(
    afterName = {"org.springframework.boot.actuate.autoconfigure.observation.ObservationAutoConfiguration"}
)
@ConditionalOnClass({ChatModel.class})
@EnableConfigurationProperties({ChatObservationProperties.class})
public class ChatObservationAutoConfiguration {
    private static final Logger logger = LoggerFactory.getLogger(ChatObservationAutoConfiguration.class);

    private static void logPromptContentWarning() {
        logger.warn("You have enabled logging out the prompt content with the risk of exposing sensitive or private information. Please, be careful!");
    }

    private static void logCompletionWarning() {
        logger.warn("You have enabled logging out the completion content with the risk of exposing sensitive or private information. Please, be careful!");
    }

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnBean({MeterRegistry.class})
    ChatModelMeterObservationHandler chatModelMeterObservationHandler(ObjectProvider<MeterRegistry> meterRegistry) {
        return new ChatModelMeterObservationHandler((MeterRegistry)meterRegistry.getObject());
    }

    @Configuration(
        proxyBeanMethods = false
    )
    @ConditionalOnClass({Tracer.class})
    @ConditionalOnBean({Tracer.class})
    static class TracerPresentObservationConfiguration {
        @Bean
        @ConditionalOnMissingBean(
            value = {ChatModelPromptContentObservationHandler.class},
            name = {"chatModelPromptContentObservationHandler"}
        )
        @ConditionalOnProperty(
            prefix = "spring.ai.chat.observations",
            name = {"log-prompt"},
            havingValue = "true"
        )
        TracingAwareLoggingObservationHandler<ChatModelObservationContext> chatModelPromptContentObservationHandler(Tracer tracer) {
            ChatObservationAutoConfiguration.logPromptContentWarning();
            return new TracingAwareLoggingObservationHandler(new ChatModelPromptContentObservationHandler(), tracer);
        }

        @Bean
        @ConditionalOnMissingBean(
            value = {ChatModelCompletionObservationHandler.class},
            name = {"chatModelCompletionObservationHandler"}
        )
        @ConditionalOnProperty(
            prefix = "spring.ai.chat.observations",
            name = {"log-completion"},
            havingValue = "true"
        )
        TracingAwareLoggingObservationHandler<ChatModelObservationContext> chatModelCompletionObservationHandler(Tracer tracer) {
            ChatObservationAutoConfiguration.logCompletionWarning();
            return new TracingAwareLoggingObservationHandler(new ChatModelCompletionObservationHandler(), tracer);
        }

        @Bean
        @ConditionalOnMissingBean
        @ConditionalOnProperty(
            prefix = "spring.ai.chat.observations",
            name = {"include-error-logging"},
            havingValue = "true"
        )
        ErrorLoggingObservationHandler errorLoggingObservationHandler(Tracer tracer) {
            return new ErrorLoggingObservationHandler(tracer, List.of(EmbeddingModelObservationContext.class, ImageModelObservationContext.class, ChatModelObservationContext.class, ChatClientObservationContext.class, AdvisorObservationContext.class));
        }
    }

    @Configuration(
        proxyBeanMethods = false
    )
    @ConditionalOnMissingClass({"io.micrometer.tracing.Tracer"})
    static class TracerNotPresentObservationConfiguration {
        @Bean
        @ConditionalOnMissingBean
        @ConditionalOnProperty(
            prefix = "spring.ai.chat.observations",
            name = {"log-prompt"},
            havingValue = "true"
        )
        ChatModelPromptContentObservationHandler chatModelPromptContentObservationHandler() {
            ChatObservationAutoConfiguration.logPromptContentWarning();
            return new ChatModelPromptContentObservationHandler();
        }

        @Bean
        @ConditionalOnMissingBean
        @ConditionalOnProperty(
            prefix = "spring.ai.chat.observations",
            name = {"log-completion"},
            havingValue = "true"
        )
        ChatModelCompletionObservationHandler chatModelCompletionObservationHandler() {
            ChatObservationAutoConfiguration.logCompletionWarning();
            return new ChatModelCompletionObservationHandler();
        }
    }
}

package org.springframework.ai.chat.observation;

import java.util.List;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import org.springframework.ai.content.Content;
import org.springframework.ai.observation.ObservabilityHelper;
import org.springframework.util.CollectionUtils;

public class ChatModelPromptContentObservationHandler implements ObservationHandler<ChatModelObservationContext> {

    private static final Logger logger = LoggerFactory.getLogger(ChatModelPromptContentObservationHandler.class);

    @Override
    public void onStop(ChatModelObservationContext context) {
       logger.info("Chat Model Prompt Content:\n{}", ObservabilityHelper.concatenateStrings(prompt(context)));
    }

    private List<String> prompt(ChatModelObservationContext context) {
       if (CollectionUtils.isEmpty(context.getRequest().getInstructions())) {
          return List.of();
       }

       return context.getRequest().getInstructions().stream().map(Content::getText).toList();
    }

    @Override
    public boolean supportsContext(Observation.Context context) {
       return context instanceof ChatModelObservationContext;
    }

}

package org.springframework.ai.chat.observation;

import java.util.List;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationHandler;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import org.springframework.ai.observation.ObservabilityHelper;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;

public class ChatModelCompletionObservationHandler implements ObservationHandler<ChatModelObservationContext> {

    private static final Logger logger = LoggerFactory.getLogger(ChatModelCompletionObservationHandler.class);

    @Override
    public void onStop(ChatModelObservationContext context) {
       logger.info("Chat Model Completion:\n{}", ObservabilityHelper.concatenateStrings(completion(context)));
    }

    private List<String> completion(ChatModelObservationContext context) {
       if (context.getResponse() == null || context.getResponse().getResults() == null
             || CollectionUtils.isEmpty(context.getResponse().getResults())) {
          return List.of();
       }

       if (!StringUtils.hasText(context.getResponse().getResult().getOutput().getText())) {
          return List.of();
       }

       return context.getResponse()
          .getResults()
          .stream()
          .filter(generation -> generation.getOutput() != null
                && StringUtils.hasText(generation.getOutput().getText()))
          .map(generation -> generation.getOutput().getText())
          .toList();
    }

    @Override
    public boolean supportsContext(Observation.Context context) {
       return context instanceof ChatModelObservationContext;
    }

}

package org.springframework.ai.model.observation;

import io.micrometer.observation.Observation;

import org.springframework.ai.observation.AiOperationMetadata;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;


public class ModelObservationContext<REQ, RES> extends Observation.Context {

    private final REQ request;

    private final AiOperationMetadata operationMetadata;

    @Nullable
    private RES response;

    public ModelObservationContext(REQ request, AiOperationMetadata operationMetadata) {
       Assert.notNull(request, "request cannot be null");
       Assert.notNull(operationMetadata, "operationMetadata cannot be null");
       this.request = request;
       this.operationMetadata = operationMetadata;
    }

    public REQ getRequest() {
       return this.request;
    }

    public AiOperationMetadata getOperationMetadata() {
       return this.operationMetadata;
    }

    @Nullable
    public RES getResponse() {
       return this.response;
    }

    public void setResponse(RES response) {
       Assert.notNull(response, "response cannot be null");
       this.response = response;
    }

}

package org.springframework.ai.chat.observation;

import org.springframework.ai.chat.model.ChatResponse;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.model.observation.ModelObservationContext;
import org.springframework.ai.observation.AiOperationMetadata;
import org.springframework.ai.observation.conventions.AiOperationType;

public class ChatModelObservationContext extends ModelObservationContext<Prompt, ChatResponse> {

    ChatModelObservationContext(Prompt prompt, String provider) {
       super(prompt,
             AiOperationMetadata.builder().operationType(AiOperationType.CHAT.value()).provider(provider).build());
    }

    public static Builder builder() {
       return new Builder();
    }

    public static final class Builder {

       private Prompt prompt;

       private String provider;

       private Builder() {
       }

       public Builder prompt(Prompt prompt) {
          this.prompt = prompt;
          return this;
       }

       public Builder provider(String provider) {
          this.provider = provider;
          return this;
       }

       public ChatModelObservationContext build() {
          return new ChatModelObservationContext(this.prompt, this.provider);
       }

    }

}

package org.springframework.ai.model.observation;

import java.util.ArrayList;
import java.util.List;

import io.micrometer.common.KeyValue;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Tag;
import io.micrometer.observation.Observation;

import org.springframework.ai.chat.metadata.Usage;
import org.springframework.ai.observation.conventions.AiObservationMetricAttributes;
import org.springframework.ai.observation.conventions.AiObservationMetricNames;
import org.springframework.ai.observation.conventions.AiTokenType;

public final class ModelUsageMetricsGenerator {

    private static final String DESCRIPTION = "Measures number of input and output tokens used";

    private ModelUsageMetricsGenerator() {
    }

    public static void generate(Usage usage, Observation.Context context, MeterRegistry meterRegistry) {

       if (usage.getPromptTokens() != null) {
          Counter.builder(AiObservationMetricNames.TOKENUSAGE.value())
             .tag(AiObservationMetricAttributes.TOKENTYPE.value(), AiTokenType.INPUT.value())
             .description(DESCRIPTION)
             .tags(createTags(context))
             .register(meterRegistry)
             .increment(usage.getPromptTokens());
       }

       if (usage.getCompletionTokens() != null) {
          Counter.builder(AiObservationMetricNames.TOKENUSAGE.value())
             .tag(AiObservationMetricAttributes.TOKENTYPE.value(), AiTokenType.OUTPUT.value())
             .description(DESCRIPTION)
             .tags(createTags(context))
             .register(meterRegistry)
             .increment(usage.getCompletionTokens());
       }

       if (usage.getTotalTokens() != null) {
          Counter.builder(AiObservationMetricNames.TOKENUSAGE.value())
             .tag(AiObservationMetricAttributes.TOKENTYPE.value(), AiTokenType.TOTAL.value())
             .description(DESCRIPTION)
             .tags(createTags(context))
             .register(meterRegistry)
             .increment(usage.getTotalTokens());
       }

    }

    private static List<Tag> createTags(Observation.Context context) {
       List<Tag> tags = new ArrayList<>();
       for (KeyValue keyValue : context.getLowCardinalityKeyValues()) {
          tags.add(Tag.of(keyValue.getKey(), keyValue.getValue()));
       }
       return tags;
    }

}

package org.springframework.ai.chat.observation;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationConvention;


public interface ChatModelObservationConvention extends ObservationConvention<ChatModelObservationContext> {

    @Override
    default boolean supportsContext(Observation.Context context) {
       return context instanceof ChatModelObservationContext;
    }

}

package org.springframework.ai.chat.observation;

import java.util.HashSet;
import java.util.Set;
import java.util.StringJoiner;

import io.micrometer.common.KeyValue;
import io.micrometer.common.KeyValues;

import org.springframework.ai.chat.prompt.ChatOptions;
import org.springframework.ai.model.tool.ToolCallingChatOptions;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;

public class DefaultChatModelObservationConvention implements ChatModelObservationConvention {

    public static final String DEFAULTNAME = "genai.client.operation";

    private static final KeyValue REQUESTMODELNONE = KeyValue
       .of(ChatModelObservationDocumentation.LowCardinalityKeyNames.REQUESTMODEL, KeyValue.NONEVALUE);

    private static final KeyValue RESPONSEMODELNONE = KeyValue
       .of(ChatModelObservationDocumentation.LowCardinalityKeyNames.RESPONSEMODEL, KeyValue.NONEVALUE);

    @Override
    public String getName() {
       return DEFAULTNAME;
    }

    @Override
    public String getContextualName(ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (StringUtils.hasText(options.getModel())) {
          return "%s %s".formatted(context.getOperationMetadata().operationType(), options.getModel());
       }
       return context.getOperationMetadata().operationType();
    }

    @Override
    public KeyValues getLowCardinalityKeyValues(ChatModelObservationContext context) {
       return KeyValues.of(aiOperationType(context), aiProvider(context), requestModel(context),
             responseModel(context));
    }

    protected KeyValue aiOperationType(ChatModelObservationContext context) {
       return KeyValue.of(ChatModelObservationDocumentation.LowCardinalityKeyNames.AIOPERATIONTYPE,
             context.getOperationMetadata().operationType());
    }

    protected KeyValue aiProvider(ChatModelObservationContext context) {
       return KeyValue.of(ChatModelObservationDocumentation.LowCardinalityKeyNames.AIPROVIDER,
             context.getOperationMetadata().provider());
    }

    protected KeyValue requestModel(ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (StringUtils.hasText(options.getModel())) {
          return KeyValue.of(ChatModelObservationDocumentation.LowCardinalityKeyNames.REQUESTMODEL,
                options.getModel());
       }
       return REQUESTMODELNONE;
    }

    protected KeyValue responseModel(ChatModelObservationContext context) {
       if (context.getResponse() != null && context.getResponse().getMetadata() != null
             && StringUtils.hasText(context.getResponse().getMetadata().getModel())) {
          return KeyValue.of(ChatModelObservationDocumentation.LowCardinalityKeyNames.RESPONSEMODEL,
                context.getResponse().getMetadata().getModel());
       }
       return RESPONSEMODELNONE;
    }

    @Override
    public KeyValues getHighCardinalityKeyValues(ChatModelObservationContext context) {
       var keyValues = KeyValues.empty();
       // Request
       keyValues = requestFrequencyPenalty(keyValues, context);
       keyValues = requestMaxTokens(keyValues, context);
       keyValues = requestPresencePenalty(keyValues, context);
       keyValues = requestStopSequences(keyValues, context);
       keyValues = requestTemperature(keyValues, context);
       keyValues = requestTools(keyValues, context);
       keyValues = requestTopK(keyValues, context);
       keyValues = requestTopP(keyValues, context);
       // Response
       keyValues = responseFinishReasons(keyValues, context);
       keyValues = responseId(keyValues, context);
       keyValues = usageInputTokens(keyValues, context);
       keyValues = usageOutputTokens(keyValues, context);
       keyValues = usageTotalTokens(keyValues, context);
       return keyValues;
    }

    // Request

    protected KeyValues requestFrequencyPenalty(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (options.getFrequencyPenalty() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTFREQUENCYPENALTY.asString(),
                String.valueOf(options.getFrequencyPenalty()));
       }
       return keyValues;
    }

    protected KeyValues requestMaxTokens(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (options.getMaxTokens() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTMAXTOKENS.asString(),
                String.valueOf(options.getMaxTokens()));
       }
       return keyValues;
    }

    protected KeyValues requestPresencePenalty(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (options.getPresencePenalty() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTPRESENCEPENALTY.asString(),
                String.valueOf(options.getPresencePenalty()));
       }
       return keyValues;
    }

    protected KeyValues requestStopSequences(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (!CollectionUtils.isEmpty(options.getStopSequences())) {
          StringJoiner stopSequencesJoiner = new StringJoiner(", ", "[", "]");
          options.getStopSequences().forEach(value -> stopSequencesJoiner.add("\"" + value + "\""));
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTSTOPSEQUENCES.asString(),
                stopSequencesJoiner.toString());
       }
       return keyValues;
    }

    protected KeyValues requestTemperature(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (options.getTemperature() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTTEMPERATURE.asString(),
                String.valueOf(options.getTemperature()));
       }
       return keyValues;
    }

    protected KeyValues requestTools(KeyValues keyValues, ChatModelObservationContext context) {
       if (!(context.getRequest().getOptions() instanceof ToolCallingChatOptions options)) {
          return keyValues;
       }

       Set<String> toolNames = new HashSet<>(options.getToolNames());
       toolNames.addAll(options.getToolCallbacks().stream().map(tc -> tc.getToolDefinition().name()).toList());

       if (!CollectionUtils.isEmpty(toolNames)) {
          StringJoiner toolNamesJoiner = new StringJoiner(", ", "[", "]");
          toolNames.forEach(value -> toolNamesJoiner.add("\"" + value + "\""));
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTTOOLNAMES.asString(),
                toolNamesJoiner.toString());
       }
       return keyValues;
    }

    protected KeyValues requestTopK(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (options.getTopK() != null) {
          return keyValues.and(ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTTOPK.asString(),
                String.valueOf(options.getTopK()));
       }
       return keyValues;
    }

    protected KeyValues requestTopP(KeyValues keyValues, ChatModelObservationContext context) {
       ChatOptions options = context.getRequest().getOptions();
       if (options.getTopP() != null) {
          return keyValues.and(ChatModelObservationDocumentation.HighCardinalityKeyNames.REQUESTTOPP.asString(),
                String.valueOf(options.getTopP()));
       }
       return keyValues;
    }

    // Response

    protected KeyValues responseFinishReasons(KeyValues keyValues, ChatModelObservationContext context) {
       if (context.getResponse() != null && !CollectionUtils.isEmpty(context.getResponse().getResults())) {
          var finishReasons = context.getResponse()
             .getResults()
             .stream()
             .filter(generation -> StringUtils.hasText(generation.getMetadata().getFinishReason()))
             .map(generation -> generation.getMetadata().getFinishReason())
             .toList();
          if (CollectionUtils.isEmpty(finishReasons)) {
             return keyValues;
          }
          StringJoiner finishReasonsJoiner = new StringJoiner(", ", "[", "]");
          finishReasons.forEach(finishReason -> finishReasonsJoiner.add("\"" + finishReason + "\""));
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.RESPONSEFINISHREASONS.asString(),
                finishReasonsJoiner.toString());
       }
       return keyValues;
    }

    protected KeyValues responseId(KeyValues keyValues, ChatModelObservationContext context) {
       if (context.getResponse() != null && context.getResponse().getMetadata() != null
             && StringUtils.hasText(context.getResponse().getMetadata().getId())) {
          return keyValues.and(ChatModelObservationDocumentation.HighCardinalityKeyNames.RESPONSEID.asString(),
                context.getResponse().getMetadata().getId());
       }
       return keyValues;
    }

    protected KeyValues usageInputTokens(KeyValues keyValues, ChatModelObservationContext context) {
       if (context.getResponse() != null && context.getResponse().getMetadata() != null
             && context.getResponse().getMetadata().getUsage() != null
             && context.getResponse().getMetadata().getUsage().getPromptTokens() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.USAGEINPUTTOKENS.asString(),
                String.valueOf(context.getResponse().getMetadata().getUsage().getPromptTokens()));
       }
       return keyValues;
    }

    protected KeyValues usageOutputTokens(KeyValues keyValues, ChatModelObservationContext context) {
       if (context.getResponse() != null && context.getResponse().getMetadata() != null
             && context.getResponse().getMetadata().getUsage() != null
             && context.getResponse().getMetadata().getUsage().getCompletionTokens() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.USAGEOUTPUTTOKENS.asString(),
                String.valueOf(context.getResponse().getMetadata().getUsage().getCompletionTokens()));
       }
       return keyValues;
    }

    protected KeyValues usageTotalTokens(KeyValues keyValues, ChatModelObservationContext context) {
       if (context.getResponse() != null && context.getResponse().getMetadata() != null
             && context.getResponse().getMetadata().getUsage() != null
             && context.getResponse().getMetadata().getUsage().getTotalTokens() != null) {
          return keyValues.and(
                ChatModelObservationDocumentation.HighCardinalityKeyNames.USAGETOTALTOKENS.asString(),
                String.valueOf(context.getResponse().getMetadata().getUsage().getTotalTokens()));
       }
       return keyValues;
    }

}

package org.springframework.ai.chat.client.observation;

import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationConvention;

public interface ChatClientObservationConvention extends ObservationConvention<ChatClientObservationContext> {
    default boolean supportsContext(Observation.Context context) {
        return context instanceof ChatClientObservationContext;
    }
}

package org.springframework.ai.chat.client.observation;

import io.micrometer.common.KeyValue;
import io.micrometer.common.KeyValues;
import java.util.ArrayList;
import java.util.List;
import org.springframework.ai.chat.client.advisor.api.Advisor;
import org.springframework.ai.chat.client.observation.ChatClientObservationDocumentation.HighCardinalityKeyNames;
import org.springframework.ai.chat.observation.ChatModelObservationDocumentation.LowCardinalityKeyNames;
import org.springframework.ai.chat.prompt.ChatOptions;
import org.springframework.ai.model.tool.ToolCallingChatOptions;
import org.springframework.ai.observation.ObservabilityHelper;
import org.springframework.ai.observation.conventions.SpringAiKind;
import org.springframework.lang.Nullable;
import org.springframework.util.CollectionUtils;
import org.springframework.util.StringUtils;

public class DefaultChatClientObservationConvention implements ChatClientObservationConvention {
    public static final String DEFAULTNAME = "spring.ai.chat.client";
    private final String name;

    public DefaultChatClientObservationConvention() {
        this("spring.ai.chat.client");
    }

    public DefaultChatClientObservationConvention(String name) {
        this.name = name;
    }

    public String getName() {
        return this.name;
    }

    @Nullable
    public String getContextualName(ChatClientObservationContext context) {
        return "%s %s".formatted(context.getOperationMetadata().provider(), SpringAiKind.CHATCLIENT.value());
    }

    public KeyValues getLowCardinalityKeyValues(ChatClientObservationContext context) {
        return KeyValues.of(new KeyValue[]{this.aiOperationType(context), this.aiProvider(context), this.springAiKind(), this.stream(context)});
    }

    protected KeyValue aiOperationType(ChatClientObservationContext context) {
        return KeyValue.of(LowCardinalityKeyNames.AIOPERATIONTYPE, context.getOperationMetadata().operationType());
    }

    protected KeyValue aiProvider(ChatClientObservationContext context) {
        return KeyValue.of(LowCardinalityKeyNames.AIPROVIDER, context.getOperationMetadata().provider());
    }

    protected KeyValue springAiKind() {
        return KeyValue.of(org.springframework.ai.chat.client.observation.ChatClientObservationDocumentation.LowCardinalityKeyNames.SPRINGAIKIND, SpringAiKind.CHATCLIENT.value());
    }

    protected KeyValue stream(ChatClientObservationContext context) {
        return KeyValue.of(org.springframework.ai.chat.client.observation.ChatClientObservationDocumentation.LowCardinalityKeyNames.STREAM, "" + context.isStream());
    }

    public KeyValues getHighCardinalityKeyValues(ChatClientObservationContext context) {
        KeyValues keyValues = KeyValues.empty();
        keyValues = this.advisors(keyValues, context);
        keyValues = this.conversationId(keyValues, context);
        keyValues = this.tools(keyValues, context);
        return keyValues;
    }

    protected KeyValues advisors(KeyValues keyValues, ChatClientObservationContext context) {
        if (CollectionUtils.isEmpty(context.getAdvisors())) {
            return keyValues;
        } else {
            List<String> advisorNames = context.getAdvisors().stream().map(Advisor::getName).toList();
            return keyValues.and(HighCardinalityKeyNames.CHATCLIENTADVISORS.asString(), ObservabilityHelper.concatenateStrings(advisorNames));
        }
    }

    protected KeyValues conversationId(KeyValues keyValues, ChatClientObservationContext context) {
        if (CollectionUtils.isEmpty(context.getRequest().context())) {
            return keyValues;
        } else {
            Object conversationIdValue = context.getRequest().context().get("chatmemoryconversationid");
            if (conversationIdValue instanceof String) {
                String conversationId = (String)conversationIdValue;
                if (StringUtils.hasText(conversationId)) {
                    return keyValues.and(HighCardinalityKeyNames.CHATCLIENTCONVERSATIONID.asString(), conversationId);
                }
            }

            return keyValues;
        }
    }

    protected KeyValues tools(KeyValues keyValues, ChatClientObservationContext context) {
        if (context.getRequest().prompt().getOptions() == null) {
            return keyValues;
        } else {
            ChatOptions var4 = context.getRequest().prompt().getOptions();
            if (var4 instanceof ToolCallingChatOptions) {
                ToolCallingChatOptions options = (ToolCallingChatOptions)var4;
                ArrayList var6 = new ArrayList(options.getToolNames());
                List toolCallbacks = options.getToolCallbacks();
                if (CollectionUtils.isEmpty(var6) && CollectionUtils.isEmpty(toolCallbacks)) {
                    return keyValues;
                } else {
                    toolCallbacks.forEach((toolCallback) -> var6.add(toolCallback.getToolDefinition().name()));
                    return keyValues.and(HighCardinalityKeyNames.CHATCLIENTTOOLNAMES.asString(), ObservabilityHelper.concatenateStrings(var6.stream().sorted().toList()));
                }
            } else {
                return keyValues;
            }
        }
    }
}

package org.springframework.ai.tool.observation;

import io.micrometer.observation.Observation;

import org.springframework.ai.observation.AiOperationMetadata;
import org.springframework.ai.observation.conventions.AiOperationType;
import org.springframework.ai.observation.conventions.AiProvider;
import org.springframework.ai.tool.definition.ToolDefinition;
import org.springframework.ai.tool.metadata.ToolMetadata;
import org.springframework.lang.Nullable;
import org.springframework.util.Assert;

public final class ToolCallingObservationContext extends Observation.Context {

    private final AiOperationMetadata operationMetadata = new AiOperationMetadata(AiOperationType.FRAMEWORK.value(),
          AiProvider.SPRINGAI.value());

    private final ToolDefinition toolDefinition;

    private final ToolMetadata toolMetadata;

    private final String toolCallArguments;

    @Nullable
    private String toolCallResult;

    private ToolCallingObservationContext(ToolDefinition toolDefinition, ToolMetadata toolMetadata,
          @Nullable String toolCallArguments, @Nullable String toolCallResult) {
       Assert.notNull(toolDefinition, "toolDefinition cannot be null");
       Assert.notNull(toolMetadata, "toolMetadata cannot be null");

       this.toolDefinition = toolDefinition;
       this.toolMetadata = toolMetadata;
       this.toolCallArguments = toolCallArguments != null ? toolCallArguments : "{}";
       this.toolCallResult = toolCallResult;
    }

    public AiOperationMetadata getOperationMetadata() {
       return this.operationMetadata;
    }

    public ToolDefinition getToolDefinition() {
       return this.toolDefinition;
    }

    public ToolMetadata getToolMetadata() {
       return this.toolMetadata;
    }

    public String getToolCallArguments() {
       return this.toolCallArguments;
    }

    @Nullable
    public String getToolCallResult() {
       return this.toolCallResult;
    }

    public void setToolCallResult(@Nullable String toolCallResult) {
       this.toolCallResult = toolCallResult;
    }

    public static Builder builder() {
       return new Builder();
    }

    public static final class Builder {

       private ToolDefinition toolDefinition;

       private ToolMetadata toolMetadata = ToolMetadata.builder().build();

       private String toolCallArguments;

       @Nullable
       private String toolCallResult;

       private Builder() {
       }

       public Builder toolDefinition(ToolDefinition toolDefinition) {
          this.toolDefinition = toolDefinition;
          return this;
       }

       public Builder toolMetadata(ToolMetadata toolMetadata) {
          this.toolMetadata = toolMetadata;
          return this;
       }

       public Builder toolCallArguments(String toolCallArguments) {
          this.toolCallArguments = toolCallArguments;
          return this;
       }

       public Builder toolCallResult(@Nullable String toolCallResult) {
          this.toolCallResult = toolCallResult;
          return this;
       }

       public ToolCallingObservationContext build() {
          return new ToolCallingObservationContext(this.toolDefinition, this.toolMetadata, this.toolCallArguments,
                this.toolCallResult);
       }

    }

}