@microsoft/agents-copilotstudio-client 1.5.0-beta.6.ga236d9a19c → 1.5.1

package/src/copilotStudioWebChat.ts

@@ -9,7 +9,8 @@ import { Activity, Attachment, ConversationAccount } from '@microsoft/agents-act
 import { Observable, BehaviorSubject, type Subscriber } from 'rxjs'
 
 import { CopilotStudioClient } from './copilotStudioClient'
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug, trace } from '@microsoft/agents-telemetry'
+import { CopilotStudioClientTraceDefinitions } from './observability'
 
 const logger = debug('copilot-studio:webchat')
 
@@ -256,144 +257,175 @@ export class CopilotStudioWebChat {
     client: CopilotStudioClient,
     settings?: CopilotStudioWebChatSettings
   ): CopilotStudioWebChatConnection {
-    logger.info('--> Creating connection between Copilot Studio and WebChat ...')
+    const managed = trace(CopilotStudioClientTraceDefinitions.createConnection)
+    managed.record({ showTyping: settings?.showTyping })
 
-    const normalizedConversationId =
+    try {
+      logger.info('--> Creating connection between Copilot Studio and WebChat ...')
+
+      const normalizedConversationId =
       settings?.conversationId && settings.conversationId.trim() !== ''
         ? settings.conversationId.trim()
         : undefined
-    const shouldStart = settings?.startConversation ?? !normalizedConversationId
-
-    let sequence = 0
-    let activitySubscriber: Subscriber<Partial<Activity>> | undefined
-    let conversation: ConversationAccount | undefined
-    let activeConversationId: string | undefined = normalizedConversationId
-    let ended = false
-    let started = false
-
-    const connectionStatus$ = new BehaviorSubject(0)
-    const activity$ = createObservable<Partial<Activity>>(async (subscriber) => {
-      activitySubscriber = subscriber
-
-      const handleAcknowledgementOnce = once(async (): Promise<void> => {
-        connectionStatus$.next(2)
-        await Promise.resolve() // Webchat requires an extra tick to process the connection status change
-      })
-
-      // When resuming (shouldStart === false), transition straight to connected
-      if (!shouldStart || started) {
-        await handleAcknowledgementOnce()
-        return
-      }
-      started = true
+      const shouldStart = settings?.startConversation ?? !normalizedConversationId
+
+      let sequence = 0
+      let activitySubscriber: Subscriber<Partial<Activity>> | undefined
+      let conversation: ConversationAccount | undefined
+      let activeConversationId: string | undefined = normalizedConversationId
+      let ended = false
+      let started = false
+
+      const connectionStatus$ = new BehaviorSubject(0)
+      const activity$ = createObservable<Partial<Activity>>(async (subscriber) => {
+        try {
+          activitySubscriber = subscriber
+
+          const handleAcknowledgementOnce = once(async (): Promise<void> => {
+            connectionStatus$.next(2)
+            await Promise.resolve() // Webchat requires an extra tick to process the connection status change
+          })
+
+          // When resuming (shouldStart === false), transition straight to connected
+          if (!shouldStart || started) {
+            await handleAcknowledgementOnce()
+            return
+          }
+          started = true
 
-      logger.debug('--> Connection established.')
-      notifyTyping()
+          logger.debug('--> Connection established.')
+          notifyTyping()
 
-      for await (const activity of client.startConversationStreaming()) {
-        delete activity.replyToId
-        if (!conversation && activity.conversation) {
-          conversation = activity.conversation
-        }
-        if (activity.conversation?.id) {
-          activeConversationId = activity.conversation.id
+          for await (const activity of client.startConversationStreaming()) {
+            delete activity.replyToId
+            if (!conversation && activity.conversation) {
+              conversation = activity.conversation
+            }
+            if (activity.conversation?.id) {
+              activeConversationId = activity.conversation.id
+            }
+            await handleAcknowledgementOnce()
+            notifyActivity(activity)
+            managed.actions.receivedFromCopilot(activity)
+          }
+          // If no activities received from bot, we should still acknowledge.
+          await handleAcknowledgementOnce()
+        } catch (error) {
+          throw managed.fail(error)
+        } finally {
+          managed.end()
         }
-        await handleAcknowledgementOnce()
-        notifyActivity(activity)
-      }
-      // If no activities received from bot, we should still acknowledge.
-      await handleAcknowledgementOnce()
-    })
-
-    const notifyActivity = (activity: Partial<Activity>) => {
-      const newActivity = {
-        ...activity,
-        timestamp: new Date().toISOString(),
-        channelData: {
-          ...activity.channelData,
-          'webchat:sequence-id': sequence,
-        },
-      }
-      sequence++
-      logger.debug(`Notify '${newActivity.type}' activity to WebChat:`, newActivity)
-      activitySubscriber?.next(newActivity)
-    }
+      })
 
-    const notifyTyping = () => {
-      if (!settings?.showTyping) {
-        return
+      const notifyActivity = (activity: Partial<Activity>) => {
+        const newActivity = {
+          ...activity,
+          timestamp: new Date().toISOString(),
+          channelData: {
+            ...activity.channelData,
+            'webchat:sequence-id': sequence,
+          },
+        }
+        sequence++
+        logger.debug(`Notify '${newActivity.type}' activity to WebChat:`, newActivity)
+        activitySubscriber?.next(newActivity)
       }
 
-      const from = conversation
-        ? { id: conversation.id, name: conversation.name }
-        : { id: 'agent', name: 'Agent' }
-      notifyActivity({ type: 'typing', from })
-    }
-
-    return {
-      connectionStatus$,
-      activity$,
-
-      get conversationId () {
-        return activeConversationId
-      },
-
-      postActivity (activity: Activity) {
-        logger.info('--> Preparing to send activity to Copilot Studio ...')
-
-        if (!activity) {
-          throw new Error('Activity cannot be null.')
+      const notifyTyping = () => {
+        if (!settings?.showTyping) {
+          return
         }
 
-        if (ended) {
-          throw new Error('Connection has been ended.')
-        }
+        const from = conversation
+          ? { id: conversation.id, name: conversation.name }
+          : { id: 'agent', name: 'Agent' }
+        notifyActivity({ type: 'typing', from })
+      }
 
-        if (!activitySubscriber) {
-          throw new Error('Activity subscriber is not initialized.')
-        }
+      return {
+        connectionStatus$,
+        activity$,
+
+        get conversationId () {
+          return activeConversationId
+        },
 
-        return createObservable<string>(async (subscriber) => {
+        postActivity (activity: Activity) {
           try {
-            logger.info('--> Sending activity to Copilot Studio ...')
-            const newActivity = Activity.fromObject({
-              ...activity,
-              id: uuid(),
-              attachments: await processAttachments(activity)
-            })
+            logger.info('--> Preparing to send activity to Copilot Studio ...')
 
-            notifyActivity(newActivity)
-            notifyTyping()
+            if (!activity) {
+              throw new Error('Activity cannot be null.')
+            }
 
-            // Notify WebChat immediately that the message was sent
-            subscriber.next(newActivity.id!)
+            if (ended) {
+              throw new Error('Connection has been ended.')
+            }
 
-            // Stream the agent's response, passing activeConversationId for URL routing
-            for await (const responseActivity of client.sendActivityStreaming(newActivity, activeConversationId)) {
-              if (!activeConversationId && responseActivity.conversation?.id) {
-                activeConversationId = responseActivity.conversation.id
-              }
-              notifyActivity(responseActivity)
-              logger.info('<-- Activity received correctly from Copilot Studio.')
+            if (!activitySubscriber) {
+              throw new Error('Activity subscriber is not initialized.')
             }
 
-            subscriber.complete()
+            const result = createObservable<string>(async (subscriber) => {
+              try {
+                logger.info('--> Sending activity to Copilot Studio ...')
+                const newActivity = Activity.fromObject({
+                  ...activity,
+                  id: uuid(),
+                  attachments: await processAttachments(activity)
+                })
+
+                notifyActivity(newActivity)
+                managed.actions.sentToWebChat(newActivity)
+                notifyTyping()
+
+                // Notify WebChat immediately that the message was sent
+                subscriber.next(newActivity.id!)
+
+                // Stream the agent's response, passing activeConversationId for URL routing
+                for await (const responseActivity of client.sendActivityStreaming(newActivity, activeConversationId)) {
+                  if (!activeConversationId && responseActivity.conversation?.id) {
+                    activeConversationId = responseActivity.conversation.id
+                  }
+                  notifyActivity(responseActivity)
+                  managed.actions.receivedFromCopilot(responseActivity)
+                  logger.info('<-- Activity received correctly from Copilot Studio.')
+                }
+
+                subscriber.complete()
+              } catch (error) {
+                logger.error('Error sending Activity to Copilot Studio:', error)
+                subscriber.error(error)
+                managed.fail(error)
+              } finally {
+                managed.end()
+              }
+            })
+
+            return result
           } catch (error) {
-            logger.error('Error sending Activity to Copilot Studio:', error)
-            subscriber.error(error)
+            throw managed.fail(error)
+          } finally {
+            managed.end()
           }
-        })
-      },
-
-      end () {
-        logger.info('--> Ending connection between Copilot Studio and WebChat ...')
-        ended = true
-        connectionStatus$.complete()
-        if (activitySubscriber) {
-          activitySubscriber.complete()
-          activitySubscriber = undefined
-        }
-      },
+        },
+
+        end () {
+          logger.info('--> Ending connection between Copilot Studio and WebChat ...')
+          ended = true
+          connectionStatus$.complete()
+          if (activitySubscriber) {
+            activitySubscriber.complete()
+            activitySubscriber = undefined
+          }
+          // End the connection span
+          managed.end()
+        },
+      }
+    } catch (error) {
+      throw managed.fail(error)
+    } finally {
+      managed.end()
     }
   }
 }

package/src/observability/index.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+export * from './metrics'
+export * from './traces'

package/src/observability/metrics.ts

@@ -0,0 +1,63 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+import { metric, MetricNames } from '@microsoft/agents-telemetry'
+
+export const CopilotStudioClientMetrics = {
+  // Counters
+  activitiesReceivedCounter: metric.counter(MetricNames.CSC_ACTIVITIES_RECEIVED, {
+    unit: 'activities',
+    description: 'Total number of activities received by the Copilot Studio client'
+  }),
+
+  activitiesSentCounter: metric.counter(MetricNames.CSC_ACTIVITIES_SENT, {
+    unit: 'activities',
+    description: 'Total number of activities sent to Copilot Studio'
+  }),
+
+  conversationsStartedCounter: metric.counter(MetricNames.CSC_CONVERSATIONS_STARTED, {
+    unit: 'conversations',
+    description: 'Total number of conversations started with Copilot Studio'
+  }),
+
+  webchatConnectionsCounter: metric.counter(MetricNames.CSC_WEBCHAT_CONNECTIONS, {
+    unit: 'connections',
+    description: 'Total number of webchat connections created with Copilot Studio'
+  }),
+
+  requestsCounter: metric.counter(MetricNames.CSC_REQUEST_COUNT, {
+    unit: 'requests',
+    description: 'Total number of HTTP/SSE requests made to Copilot Studio'
+  }),
+
+  requestsErrorCounter: metric.counter(MetricNames.CSC_REQUEST_ERRORS, {
+    unit: 'requests',
+    description: 'Total number of failed requests to Copilot Studio'
+  }),
+
+  executeStreamingCounter: metric.counter(MetricNames.CSC_EXECUTE_STREAMING, {
+    unit: 'operations',
+    description: 'Total number of execute streaming operations'
+  }),
+
+  subscribeAsyncCounter: metric.counter(MetricNames.CSC_SUBSCRIBE_ASYNC, {
+    unit: 'operations',
+    description: 'Total number of subscribeAsync operations'
+  }),
+
+  subscribeEventCounter: metric.counter(MetricNames.CSC_SUBSCRIBE_EVENT, {
+    unit: 'events',
+    description: 'Total number of events received via subscribeAsync'
+  }),
+
+  // Duration Histograms
+  streamDuration: metric.histogram(MetricNames.CSC_STREAM_DURATION, {
+    unit: 'ms',
+    description: 'Duration of SSE stream sessions in milliseconds'
+  }),
+
+  requestDuration: metric.histogram(MetricNames.CSC_REQUEST_DURATION, {
+    unit: 'ms',
+    description: 'Duration of requests to Copilot Studio in milliseconds'
+  })
+}

package/src/observability/traces.ts

@@ -0,0 +1,171 @@
+import { Activity } from '@microsoft/agents-activity'
+import { trace, SpanNames } from '@microsoft/agents-telemetry'
+import { CopilotStudioClientMetrics } from './metrics'
+import { SubscribeEvent } from '../subscribeEvent'
+
+export const CopilotStudioClientTraceDefinitions = {
+  createConnection: trace.define({
+    name: SpanNames.COPILOT_CREATE_CONNECTION,
+    record: {
+      showTyping: false,
+    },
+    actions: ({ span }) => ({
+      receivedFromCopilot (activity: Activity) {
+        span.addEvent('activity.received.from.copilot.studio', {
+          'copilot.webchat.activity.type': activity.type ?? 'unknown',
+          'copilot.webchat.activity.conversation_id': activity.conversation?.id ?? 'unknown'
+        })
+      },
+      sentToWebChat (activity: Activity) {
+        span.addEvent('activity.sent.to.webchat', {
+          'copilot.webchat.activity.type': activity.type ?? 'unknown',
+          'copilot.webchat.activity.conversation_id': activity.conversation?.id ?? 'unknown'
+        })
+      },
+    }),
+    end ({ span, record }) {
+      const attributes = {
+        'copilot.webchat.show_typing': record.showTyping ?? 'unknown'
+      }
+
+      span.setAttributes(attributes)
+      CopilotStudioClientMetrics.webchatConnectionsCounter.add(1, attributes)
+    }
+  }),
+  postRequest: trace.define({
+    name: SpanNames.COPILOT_POST_REQUEST,
+    record: {
+      url: '',
+      method: ''
+    },
+    actions: ({ span }) => ({
+      receivedFromCopilot (activity: Activity) {
+        const attributes = {
+          'copilot.activity.type': activity.type ?? 'unknown',
+          'copilot.activity.conversation_id': activity.conversation?.id ?? 'unknown'
+        }
+
+        span.addEvent('activity.received', {
+          'copilot.post_request.activity.type': attributes['copilot.activity.type'],
+          'copilot.post_request.activity.conversation_id': attributes['copilot.activity.conversation_id']
+        })
+        CopilotStudioClientMetrics.activitiesReceivedCounter.add(1, attributes)
+      }
+    }),
+    end ({ span, record, duration, error }) {
+      const attributes = {
+        'copilot.post_request.url': record.url ?? 'unknown',
+        'copilot.post_request.method': record.method ?? 'unknown'
+      }
+      const metricAttributes = {
+        operation: 'postRequestAsync',
+        'copilot.post_request.url': attributes['copilot.post_request.url'],
+        'copilot.post_request.method': attributes['copilot.post_request.method']
+      }
+
+      span.setAttributes(attributes)
+      CopilotStudioClientMetrics.requestsCounter.add(1, metricAttributes)
+      CopilotStudioClientMetrics.streamDuration.record(duration, metricAttributes)
+
+      if (error) {
+        CopilotStudioClientMetrics.requestsErrorCounter.add(1, {
+          ...metricAttributes,
+          'error.type': error instanceof Error ? error.name : typeof error,
+        })
+      }
+    }
+  }),
+  startConversation: trace.define({
+    name: SpanNames.COPILOT_START_CONVERSATION,
+    record: {
+      shouldEmitStartEvent: false,
+    },
+    end ({ span, record, duration }) {
+      const attributes = record.shouldEmitStartEvent
+        ? { 'copilot.emit_start_event': true }
+        : { 'copilot.request': true }
+      const metricAttributes = {
+        operation: 'startConversationStreaming',
+        ...attributes,
+      }
+
+      span.setAttributes(attributes)
+      CopilotStudioClientMetrics.conversationsStartedCounter.add(1, metricAttributes)
+      CopilotStudioClientMetrics.requestDuration.record(duration, metricAttributes)
+    }
+  }),
+  sendActivity: trace.define({
+    name: SpanNames.COPILOT_SEND_ACTIVITY,
+    record: {
+      activity: Activity.fromObject({ type: 'unknown' }),
+    },
+    end ({ span, record, duration }) {
+      const attributes = {
+        'copilot.activity.type': record.activity.type ?? 'unknown',
+        'copilot.activity.conversation_id': record.activity.conversation?.id ?? 'unknown'
+      }
+      const metricAttributes = {
+        operation: 'sendActivityStreaming',
+        ...attributes,
+      }
+
+      span.setAttributes(attributes)
+      CopilotStudioClientMetrics.activitiesSentCounter.add(1, attributes)
+      CopilotStudioClientMetrics.requestDuration.record(duration, metricAttributes)
+    }
+  }),
+  executeStreaming: trace.define({
+    name: SpanNames.COPILOT_EXECUTE_STREAMING,
+    record: {
+      activity: Activity.fromObject({ type: 'unknown' }),
+      conversationId: 'unknown'
+    },
+    end ({ span, record, duration }) {
+      const attributes = {
+        'copilot.activity.type': record.activity.type ?? 'unknown',
+        'copilot.activity.conversation_id': record.conversationId ?? 'unknown'
+      }
+      const metricAttributes = {
+        operation: 'executeStreaming',
+        ...attributes,
+      }
+
+      span.setAttributes(attributes)
+      CopilotStudioClientMetrics.executeStreamingCounter.add(1, attributes)
+      CopilotStudioClientMetrics.requestDuration.record(duration, metricAttributes)
+    }
+  }),
+  subscribeAsync: trace.define({
+    name: SpanNames.COPILOT_SUBSCRIBE_ASYNC,
+    record: {
+      conversationId: 'unknown',
+      lastReceivedEventId: 'unknown'
+    },
+    actions: ({ span }) => ({
+      eventReceivedFromCopilot (event: SubscribeEvent) {
+        const attributes = {
+          'copilot.subscribe_async.event.id': event.eventId ?? 'unknown',
+          'copilot.subscribe_async.event.activity.type': event.activity.type ?? 'unknown',
+        }
+
+        span.addEvent('event.received', attributes)
+        CopilotStudioClientMetrics.subscribeEventCounter.add(1, attributes)
+      }
+    }),
+    end ({ span, record, duration }) {
+      const attributes = {
+        'copilot.subscribe_async.conversation_id': record.conversationId ?? 'unknown',
+        'copilot.subscribe_async.last_received_event_id': record.lastReceivedEventId ?? 'unknown'
+      }
+      const metricAttributes = {
+        operation: 'subscribeAsync',
+        'copilot.conversation_id': attributes['copilot.subscribe_async.conversation_id'],
+        'copilot.last_received_event_id': attributes['copilot.subscribe_async.last_received_event_id']
+      }
+
+      span.setAttributes(attributes)
+      CopilotStudioClientMetrics.subscribeAsyncCounter.add(1, metricAttributes)
+      CopilotStudioClientMetrics.streamDuration.record(duration, metricAttributes)
+    }
+  })
+}

package/src/powerPlatformEnvironment.ts

@@ -5,7 +5,7 @@
 
 import { AgentType } from './agentType'
 import { ConnectionSettings } from './connectionSettings'
-import { debug } from '@microsoft/agents-activity/logger'
+import { debug } from '@microsoft/agents-telemetry'
 import { PowerPlatformCloud } from './powerPlatformCloud'
 import { PrebuiltBotStrategy } from './strategies/prebuiltBotStrategy'
 import { PublishedBotStrategy } from './strategies/publishedBotStrategy'