@fedify/vocab 2.3.0-dev.1131 → 2.3.0-dev.1145

package/deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.3.0-dev.1131+553b59b8",
+  "version": "2.3.0-dev.1145+3fe78022",
   "license": "MIT",
   "exports": {
     ".": "./src/mod.ts"

package/dist/mod.cjs

@@ -33,7 +33,7 @@ let _fedify_vocab_runtime_temporal = require("@fedify/vocab-runtime/temporal");
 let es_toolkit = require("es-toolkit");
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.3.0-dev.1131+553b59b8";
+var version = "2.3.0-dev.1145+3fe78022";
 //#endregion
 //#region src/type.ts
 function getTypeId(object) {
@@ -47333,6 +47333,53 @@ function getEntityTypeById(id) {
 }
 //#endregion
 //#region src/actor.ts
+const ACTOR_DISCOVERY_HISTOGRAM_BUCKETS = [
+	5,
+	10,
+	25,
+	50,
+	75,
+	100,
+	250,
+	500,
+	750,
+	1e3,
+	2500,
+	5e3,
+	7500,
+	1e4
+];
+const actorDiscoveryInstruments = /* @__PURE__ */ new WeakMap();
+function getActorDiscoveryInstruments(meterProvider) {
+	let instruments = actorDiscoveryInstruments.get(meterProvider);
+	if (instruments == null) {
+		const meter = meterProvider.getMeter(name, version);
+		instruments = {
+			discovery: meter.createCounter("activitypub.actor.discovery", {
+				description: "Actor handle discovery attempts via getActorHandle(), classified by terminal outcome.",
+				unit: "{discovery}"
+			}),
+			discoveryDuration: meter.createHistogram("activitypub.actor.discovery.duration", {
+				description: "Duration of getActorHandle() actor discovery calls.",
+				unit: "ms",
+				advice: { explicitBucketBoundaries: [...ACTOR_DISCOVERY_HISTOGRAM_BUCKETS] }
+			})
+		};
+		actorDiscoveryInstruments.set(meterProvider, instruments);
+	}
+	return instruments;
+}
+function getActorDiscoveryRemoteHost(actor) {
+	const id = actor instanceof URL ? actor : actor.id;
+	if (id == null) return void 0;
+	return id.hostname === "" ? void 0 : id.hostname;
+}
+var ActorHandleNotFoundError = class extends TypeError {
+	constructor() {
+		super("Actor does not have enough information to get the handle.");
+		this.name = "ActorHandleNotFoundError";
+	}
+};
 /**
 * Checks if the given object is an {@link Actor}.
 * @param object The object to check.
@@ -47399,15 +47446,29 @@ async function getActorHandle(actor, options = {}) {
 			if (actor.id != null) span.setAttribute("activitypub.actor.id", actor.id.href);
 			span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
 		}
+		const meterProvider = options.meterProvider;
+		const start = meterProvider == null ? 0 : performance.now();
+		let result = "error";
 		try {
-			return await getActorHandleInternal(actor, options);
+			const handle = await getActorHandleInternal(actor, options);
+			result = "resolved";
+			return handle;
 		} catch (error) {
+			result = error instanceof ActorHandleNotFoundError ? "not_found" : "error";
 			span.setStatus({
 				code: _opentelemetry_api.SpanStatusCode.ERROR,
 				message: String(error)
 			});
 			throw error;
 		} finally {
+			if (meterProvider != null) {
+				const attributes = { "activitypub.actor.discovery.result": result };
+				const host = getActorDiscoveryRemoteHost(actor);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				const instruments = getActorDiscoveryInstruments(meterProvider);
+				instruments.discovery.add(1, attributes);
+				instruments.discoveryDuration.record(Math.max(0, performance.now() - start), attributes);
+			}
 			span.end();
 		}
 	});
@@ -47417,7 +47478,8 @@ async function getActorHandleInternal(actor, options = {}) {
 	if (actorId != null) {
 		const result = await (0, _fedify_webfinger.lookupWebFinger)(actorId, {
 			userAgent: options.userAgent,
-			tracerProvider: options.tracerProvider
+			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider
 		});
 		if (result != null) {
 			const aliases = [...result.aliases ?? []];
@@ -47425,19 +47487,20 @@ async function getActorHandleInternal(actor, options = {}) {
 			for (const alias of aliases) {
 				const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
 				if (match != null) {
-					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider)) continue;
+					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider, options.meterProvider)) continue;
 					return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
 				}
 			}
 		}
 	}
 	if (!(actor instanceof URL) && actor.preferredUsername != null && actor.id != null) return normalizeActorHandle(`@${actor.preferredUsername}@${actor.id.host}`, options);
-	throw new TypeError("Actor does not have enough information to get the handle.");
+	throw new ActorHandleNotFoundError();
 }
-async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider) {
+async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider, meterProvider) {
 	const response = await (0, _fedify_webfinger.lookupWebFinger)(alias, {
 		userAgent,
-		tracerProvider
+		tracerProvider,
+		meterProvider
 	});
 	if (response == null) return false;
 	for (const alias of response.aliases ?? []) if (new URL(alias).href === actorId) return true;
@@ -47671,6 +47734,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 		const jrd = await (0, _fedify_webfinger.lookupWebFinger)(identifier, {
 			userAgent: options.userAgent,
 			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider,
 			allowPrivateAddress: "allowPrivateAddress" in options && options.allowPrivateAddress === true,
 			signal: options.signal
 		});

package/dist/mod.d.cts

@@ -18088,6 +18088,24 @@ declare function getEntityTypeById(id: string | URL): $EntityType | undefined;
 //#endregion
 //#region src/actor.d.ts
 /**
+* The terminal classification of a {@link getActorHandle} call, recorded as
+* the `activitypub.actor.discovery.result` attribute on the
+* `activitypub.actor.discovery` counter and
+* `activitypub.actor.discovery.duration` histogram.
+*
+*  -  `resolved`: a handle was returned to the caller.
+*  -  `not_found`: WebFinger did not yield a usable `acct:` alias and the
+*     `preferredUsername` fallback could not run.  This corresponds to the
+*     `TypeError("Actor does not have enough information…")` path.
+*  -  `error`: any other thrown exception bubbled up from the lookup.
+*
+* Per-WebFinger-call failure detail (HTTP status, parse failure, network
+* failure, etc.) lives on `webfinger.lookup` and is intentionally not
+* duplicated here.
+* @since 2.3.0
+*/
+type ActorDiscoveryResult = "resolved" | "not_found" | "error";
+/**
 * Actor types are {@link Object} types that are capable of performing
 * activities.
 */
@@ -18133,6 +18151,18 @@ interface GetActorHandleOptions extends NormalizeActorHandleOptions {
   * @since 1.3.0
   */
   tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider used to record the
+  * `activitypub.actor.discovery` counter and
+  * `activitypub.actor.discovery.duration` histogram.  When set, the same
+  * meter provider is also forwarded to the nested WebFinger lookups so
+  * each discovery emits both the actor-discovery measurements and the
+  * underlying `webfinger.lookup` measurements.  If omitted, no
+  * measurements are emitted (the helper is opt-in to avoid touching the
+  * global meter provider for callers that do not use OpenTelemetry).
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
 }
 /**
 * Gets the actor handle, of the form `@username@domain`, from the given actor
@@ -18531,4 +18561,4 @@ declare function getTypeId(object: Object$1 | Link | null): URL | null;
 */
 declare function getTypeId(object: Object$1 | Link | null | undefined): URL | null | undefined;
 //#endregion
-export { $EntityType, Accept, Activity, Actor, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { $EntityType, Accept, Activity, Actor, ActorDiscoveryResult, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/mod.d.ts

@@ -18088,6 +18088,24 @@ declare function getEntityTypeById(id: string | URL): $EntityType | undefined;
 //#endregion
 //#region src/actor.d.ts
 /**
+* The terminal classification of a {@link getActorHandle} call, recorded as
+* the `activitypub.actor.discovery.result` attribute on the
+* `activitypub.actor.discovery` counter and
+* `activitypub.actor.discovery.duration` histogram.
+*
+*  -  `resolved`: a handle was returned to the caller.
+*  -  `not_found`: WebFinger did not yield a usable `acct:` alias and the
+*     `preferredUsername` fallback could not run.  This corresponds to the
+*     `TypeError("Actor does not have enough information…")` path.
+*  -  `error`: any other thrown exception bubbled up from the lookup.
+*
+* Per-WebFinger-call failure detail (HTTP status, parse failure, network
+* failure, etc.) lives on `webfinger.lookup` and is intentionally not
+* duplicated here.
+* @since 2.3.0
+*/
+type ActorDiscoveryResult = "resolved" | "not_found" | "error";
+/**
 * Actor types are {@link Object} types that are capable of performing
 * activities.
 */
@@ -18133,6 +18151,18 @@ interface GetActorHandleOptions extends NormalizeActorHandleOptions {
   * @since 1.3.0
   */
   tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider used to record the
+  * `activitypub.actor.discovery` counter and
+  * `activitypub.actor.discovery.duration` histogram.  When set, the same
+  * meter provider is also forwarded to the nested WebFinger lookups so
+  * each discovery emits both the actor-discovery measurements and the
+  * underlying `webfinger.lookup` measurements.  If omitted, no
+  * measurements are emitted (the helper is opt-in to avoid touching the
+  * global meter provider for callers that do not use OpenTelemetry).
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
 }
 /**
 * Gets the actor handle, of the form `@username@domain`, from the given actor
@@ -18531,4 +18561,4 @@ declare function getTypeId(object: Object$1 | Link | null): URL | null;
 */
 declare function getTypeId(object: Object$1 | Link | null | undefined): URL | null | undefined;
 //#endregion
-export { $EntityType, Accept, Activity, Actor, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };
+export { $EntityType, Accept, Activity, Actor, ActorDiscoveryResult, ActorTypeName, Add, Announce, AnnounceAuthorization, AnnounceRequest, Application, Arrive, Article, Audio, Block, ChatMessage, Collection, CollectionPage, Create, CryptographicKey, DataIntegrityProof, Delete, DidService, Dislike, Document, type DocumentLoader, Emoji, EmojiReact, Endpoints, Event, Export, FediverseHandle, Flag, Follow, GetActorHandleOptions, type GetUserAgentOptions, Group, Hashtag, Ignore, Image, Intent, InteractionPolicy, InteractionRule, IntransitiveActivity, Invite, Join, LanguageString, Leave, Like, LikeAuthorization, LikeRequest, Link, Listen, LookupObjectOptions, Measure, Mention, Move, Multikey, NormalizeActorHandleOptions, Note, Object$1 as Object, ObjectLookupKind, Offer, OrderedCollection, OrderedCollectionPage, Organization, PUBLIC_COLLECTION, Page, Person, Place, Profile, PropertyValue, Proposal, Question, QuoteAuthorization, QuoteRequest, Read, Recipient, Reject, Relationship, type RemoteDocument, Remove, ReplyAuthorization, ReplyRequest, Service, Source, TentativeAccept, TentativeReject, Tombstone, Travel, TraverseCollectionOptions, Undo, Update, Video, View, getActorClassByTypeName, getActorHandle, getActorTypeName, getEntityTypeById, getTypeId, isActor, isEntityType, isFediverseHandle, lookupObject, normalizeActorHandle, parseFediverseHandle, toAcctUrl, traverseCollection };

package/dist/mod.js

@@ -9,7 +9,7 @@ import { isTemporalDuration, isTemporalInstant } from "@fedify/vocab-runtime/tem
 import { delay } from "es-toolkit";
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.3.0-dev.1131+553b59b8";
+var version = "2.3.0-dev.1145+3fe78022";
 //#endregion
 //#region src/type.ts
 function getTypeId(object) {
@@ -47309,6 +47309,53 @@ function getEntityTypeById(id) {
 }
 //#endregion
 //#region src/actor.ts
+const ACTOR_DISCOVERY_HISTOGRAM_BUCKETS = [
+	5,
+	10,
+	25,
+	50,
+	75,
+	100,
+	250,
+	500,
+	750,
+	1e3,
+	2500,
+	5e3,
+	7500,
+	1e4
+];
+const actorDiscoveryInstruments = /* @__PURE__ */ new WeakMap();
+function getActorDiscoveryInstruments(meterProvider) {
+	let instruments = actorDiscoveryInstruments.get(meterProvider);
+	if (instruments == null) {
+		const meter = meterProvider.getMeter(name, version);
+		instruments = {
+			discovery: meter.createCounter("activitypub.actor.discovery", {
+				description: "Actor handle discovery attempts via getActorHandle(), classified by terminal outcome.",
+				unit: "{discovery}"
+			}),
+			discoveryDuration: meter.createHistogram("activitypub.actor.discovery.duration", {
+				description: "Duration of getActorHandle() actor discovery calls.",
+				unit: "ms",
+				advice: { explicitBucketBoundaries: [...ACTOR_DISCOVERY_HISTOGRAM_BUCKETS] }
+			})
+		};
+		actorDiscoveryInstruments.set(meterProvider, instruments);
+	}
+	return instruments;
+}
+function getActorDiscoveryRemoteHost(actor) {
+	const id = actor instanceof URL ? actor : actor.id;
+	if (id == null) return void 0;
+	return id.hostname === "" ? void 0 : id.hostname;
+}
+var ActorHandleNotFoundError = class extends TypeError {
+	constructor() {
+		super("Actor does not have enough information to get the handle.");
+		this.name = "ActorHandleNotFoundError";
+	}
+};
 /**
 * Checks if the given object is an {@link Actor}.
 * @param object The object to check.
@@ -47375,15 +47422,29 @@ async function getActorHandle(actor, options = {}) {
 			if (actor.id != null) span.setAttribute("activitypub.actor.id", actor.id.href);
 			span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
 		}
+		const meterProvider = options.meterProvider;
+		const start = meterProvider == null ? 0 : performance.now();
+		let result = "error";
 		try {
-			return await getActorHandleInternal(actor, options);
+			const handle = await getActorHandleInternal(actor, options);
+			result = "resolved";
+			return handle;
 		} catch (error) {
+			result = error instanceof ActorHandleNotFoundError ? "not_found" : "error";
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
 				message: String(error)
 			});
 			throw error;
 		} finally {
+			if (meterProvider != null) {
+				const attributes = { "activitypub.actor.discovery.result": result };
+				const host = getActorDiscoveryRemoteHost(actor);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				const instruments = getActorDiscoveryInstruments(meterProvider);
+				instruments.discovery.add(1, attributes);
+				instruments.discoveryDuration.record(Math.max(0, performance.now() - start), attributes);
+			}
 			span.end();
 		}
 	});
@@ -47393,7 +47454,8 @@ async function getActorHandleInternal(actor, options = {}) {
 	if (actorId != null) {
 		const result = await lookupWebFinger(actorId, {
 			userAgent: options.userAgent,
-			tracerProvider: options.tracerProvider
+			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider
 		});
 		if (result != null) {
 			const aliases = [...result.aliases ?? []];
@@ -47401,19 +47463,20 @@ async function getActorHandleInternal(actor, options = {}) {
 			for (const alias of aliases) {
 				const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
 				if (match != null) {
-					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider)) continue;
+					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider, options.meterProvider)) continue;
 					return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
 				}
 			}
 		}
 	}
 	if (!(actor instanceof URL) && actor.preferredUsername != null && actor.id != null) return normalizeActorHandle(`@${actor.preferredUsername}@${actor.id.host}`, options);
-	throw new TypeError("Actor does not have enough information to get the handle.");
+	throw new ActorHandleNotFoundError();
 }
-async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider) {
+async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider, meterProvider) {
 	const response = await lookupWebFinger(alias, {
 		userAgent,
-		tracerProvider
+		tracerProvider,
+		meterProvider
 	});
 	if (response == null) return false;
 	for (const alias of response.aliases ?? []) if (new URL(alias).href === actorId) return true;
@@ -47647,6 +47710,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 		const jrd = await lookupWebFinger(identifier, {
 			userAgent: options.userAgent,
 			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider,
 			allowPrivateAddress: "allowPrivateAddress" in options && options.allowPrivateAddress === true,
 			signal: options.signal
 		});

package/dist-tests/{actor-DBM2eKvJ.mjs → actor-B38UQKg6.mjs}

@@ -1206,9 +1206,56 @@ var esm_default = new class FetchMock {
 //#endregion
 //#region deno.json
 var name = "@fedify/vocab";
-var version = "2.3.0-dev.1131+553b59b8";
+var version = "2.3.0-dev.1145+3fe78022";
 //#endregion
 //#region src/actor.ts
+const ACTOR_DISCOVERY_HISTOGRAM_BUCKETS = [
+	5,
+	10,
+	25,
+	50,
+	75,
+	100,
+	250,
+	500,
+	750,
+	1e3,
+	2500,
+	5e3,
+	7500,
+	1e4
+];
+const actorDiscoveryInstruments = /* @__PURE__ */ new WeakMap();
+function getActorDiscoveryInstruments(meterProvider) {
+	let instruments = actorDiscoveryInstruments.get(meterProvider);
+	if (instruments == null) {
+		const meter = meterProvider.getMeter(name, version);
+		instruments = {
+			discovery: meter.createCounter("activitypub.actor.discovery", {
+				description: "Actor handle discovery attempts via getActorHandle(), classified by terminal outcome.",
+				unit: "{discovery}"
+			}),
+			discoveryDuration: meter.createHistogram("activitypub.actor.discovery.duration", {
+				description: "Duration of getActorHandle() actor discovery calls.",
+				unit: "ms",
+				advice: { explicitBucketBoundaries: [...ACTOR_DISCOVERY_HISTOGRAM_BUCKETS] }
+			})
+		};
+		actorDiscoveryInstruments.set(meterProvider, instruments);
+	}
+	return instruments;
+}
+function getActorDiscoveryRemoteHost(actor) {
+	const id = actor instanceof URL ? actor : actor.id;
+	if (id == null) return void 0;
+	return id.hostname === "" ? void 0 : id.hostname;
+}
+var ActorHandleNotFoundError = class extends TypeError {
+	constructor() {
+		super("Actor does not have enough information to get the handle.");
+		this.name = "ActorHandleNotFoundError";
+	}
+};
 /**
 * Checks if the given object is an {@link Actor}.
 * @param object The object to check.
@@ -1275,15 +1322,29 @@ async function getActorHandle(actor, options = {}) {
 			if (actor.id != null) span.setAttribute("activitypub.actor.id", actor.id.href);
 			span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
 		}
+		const meterProvider = options.meterProvider;
+		const start = meterProvider == null ? 0 : performance.now();
+		let result = "error";
 		try {
-			return await getActorHandleInternal(actor, options);
+			const handle = await getActorHandleInternal(actor, options);
+			result = "resolved";
+			return handle;
 		} catch (error) {
+			result = error instanceof ActorHandleNotFoundError ? "not_found" : "error";
 			span.setStatus({
 				code: SpanStatusCode.ERROR,
 				message: String(error)
 			});
 			throw error;
 		} finally {
+			if (meterProvider != null) {
+				const attributes = { "activitypub.actor.discovery.result": result };
+				const host = getActorDiscoveryRemoteHost(actor);
+				if (host != null) attributes["activitypub.remote.host"] = host;
+				const instruments = getActorDiscoveryInstruments(meterProvider);
+				instruments.discovery.add(1, attributes);
+				instruments.discoveryDuration.record(Math.max(0, performance.now() - start), attributes);
+			}
 			span.end();
 		}
 	});
@@ -1293,7 +1354,8 @@ async function getActorHandleInternal(actor, options = {}) {
 	if (actorId != null) {
 		const result = await lookupWebFinger(actorId, {
 			userAgent: options.userAgent,
-			tracerProvider: options.tracerProvider
+			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider
 		});
 		if (result != null) {
 			const aliases = [...result.aliases ?? []];
@@ -1301,19 +1363,20 @@ async function getActorHandleInternal(actor, options = {}) {
 			for (const alias of aliases) {
 				const match = alias.match(/^acct:([^@]+)@([^@]+)$/);
 				if (match != null) {
-					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider)) continue;
+					if (new URL(`https://${match[2]}/`).hostname !== actorId.hostname && !await verifyCrossOriginActorHandle(actorId.href, alias, options.userAgent, options.tracerProvider, options.meterProvider)) continue;
 					return normalizeActorHandle(`@${match[1]}@${match[2]}`, options);
 				}
 			}
 		}
 	}
 	if (!(actor instanceof URL) && actor.preferredUsername != null && actor.id != null) return normalizeActorHandle(`@${actor.preferredUsername}@${actor.id.host}`, options);
-	throw new TypeError("Actor does not have enough information to get the handle.");
+	throw new ActorHandleNotFoundError();
 }
-async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider) {
+async function verifyCrossOriginActorHandle(actorId, alias, userAgent, tracerProvider, meterProvider) {
 	const response = await lookupWebFinger(alias, {
 		userAgent,
-		tracerProvider
+		tracerProvider,
+		meterProvider
 	});
 	if (response == null) return false;
 	for (const alias of response.aliases ?? []) if (new URL(alias).href === actorId) return true;

package/dist-tests/actor.test.mjs

@@ -1,8 +1,8 @@
 import "@js-temporal/polyfill";
 globalThis.addEventListener = () => {};
 import { j as __exportAll, r as Application, u as Group, v as Organization, w as Service, y as Person } from "./vocab-B0Z-tH4q.mjs";
-import { a as normalizeActorHandle, c as esm_default, i as isActor, n as getActorHandle, r as getActorTypeName, t as getActorClassByTypeName } from "./actor-DBM2eKvJ.mjs";
-import { test } from "@fedify/fixture";
+import { a as normalizeActorHandle, c as esm_default, i as isActor, n as getActorHandle, r as getActorTypeName, t as getActorClassByTypeName } from "./actor-B38UQKg6.mjs";
+import { createTestMeterProvider, test } from "@fedify/fixture";
 import { deepStrictEqual, ok, rejects, strictEqual, throws } from "node:assert/strict";
 //#region ../../node_modules/.pnpm/fast-check@3.23.2/node_modules/fast-check/lib/esm/check/precondition/PreconditionFailure.js
 var PreconditionFailure = class PreconditionFailure extends Error {
@@ -5691,6 +5691,103 @@ test({
 		esm_default.hardReset();
 	}
 });
+test("getActorHandle() records activitypub.actor.discovery counter", { permissions: {
+	env: true,
+	read: true
+} }, async (t) => {
+	esm_default.spyGlobal();
+	try {
+		const actorId = new URL("https://foo.example.com/@john");
+		const actor = new Person({
+			id: actorId,
+			preferredUsername: "john"
+		});
+		await t.step("records result=resolved on a successful lookup", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://foo.example.com/.well-known/webfinger?", {
+				body: { subject: "acct:johndoe@foo.example.com" },
+				headers: { "Content-Type": "application/jrd+json" }
+			});
+			const [meterProvider, recorder] = createTestMeterProvider();
+			deepStrictEqual(await getActorHandle(actor, { meterProvider }), "@johndoe@foo.example.com");
+			const counters = recorder.getMeasurements("activitypub.actor.discovery");
+			deepStrictEqual(counters.length, 1);
+			deepStrictEqual(counters[0].type, "counter");
+			deepStrictEqual(counters[0].value, 1);
+			deepStrictEqual(counters[0].attributes["activitypub.actor.discovery.result"], "resolved");
+			deepStrictEqual(counters[0].attributes["activitypub.remote.host"], "foo.example.com");
+			const durations = recorder.getMeasurements("activitypub.actor.discovery.duration");
+			deepStrictEqual(durations.length, 1);
+			deepStrictEqual(durations[0].type, "histogram");
+			deepStrictEqual(durations[0].attributes["activitypub.actor.discovery.result"], "resolved");
+			ok(typeof durations[0].value === "number" && durations[0].value >= 0);
+		});
+		await t.step("records result=resolved when WebFinger is missing but preferredUsername fallback succeeds", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://foo.example.com/.well-known/webfinger?", { status: 404 });
+			const [meterProvider, recorder] = createTestMeterProvider();
+			deepStrictEqual(await getActorHandle(actor, { meterProvider }), "@john@foo.example.com");
+			const counter = recorder.getMeasurement("activitypub.actor.discovery");
+			ok(counter != null);
+			deepStrictEqual(counter.attributes["activitypub.actor.discovery.result"], "resolved");
+		});
+		await t.step("records result=not_found when neither WebFinger nor preferredUsername yields a handle", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://foo.example.com/.well-known/webfinger?", { status: 404 });
+			const [meterProvider, recorder] = createTestMeterProvider();
+			await rejects(() => getActorHandle(actorId, { meterProvider }), TypeError);
+			const counter = recorder.getMeasurement("activitypub.actor.discovery");
+			ok(counter != null);
+			deepStrictEqual(counter.attributes["activitypub.actor.discovery.result"], "not_found");
+			deepStrictEqual(counter.attributes["activitypub.remote.host"], "foo.example.com");
+			const duration = recorder.getMeasurement("activitypub.actor.discovery.duration");
+			ok(duration != null);
+			deepStrictEqual(duration.attributes["activitypub.actor.discovery.result"], "not_found");
+		});
+		await t.step("records result=error when a malformed WebFinger alias throws TypeError", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://foo.example.com/.well-known/webfinger?", {
+				body: {
+					subject: "https://foo.example.com/@john",
+					aliases: ["acct:john@["]
+				},
+				headers: { "Content-Type": "application/jrd+json" }
+			});
+			const [meterProvider, recorder] = createTestMeterProvider();
+			await rejects(() => getActorHandle(actorId, { meterProvider }), TypeError);
+			const counter = recorder.getMeasurement("activitypub.actor.discovery");
+			ok(counter != null);
+			deepStrictEqual(counter.attributes["activitypub.actor.discovery.result"], "error");
+		});
+		await t.step("propagates meterProvider into the nested webfinger.lookup", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://foo.example.com/.well-known/webfinger?", {
+				body: { subject: "acct:johndoe@foo.example.com" },
+				headers: { "Content-Type": "application/jrd+json" }
+			});
+			const [meterProvider, recorder] = createTestMeterProvider();
+			await getActorHandle(actor, { meterProvider });
+			const webFingerCounter = recorder.getMeasurement("webfinger.lookup");
+			ok(webFingerCounter != null);
+			deepStrictEqual(webFingerCounter.attributes["webfinger.lookup.result"], "found");
+		});
+		await t.step("omits measurements when no meterProvider is provided", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://foo.example.com/.well-known/webfinger?", {
+				body: { subject: "acct:johndoe@foo.example.com" },
+				headers: { "Content-Type": "application/jrd+json" }
+			});
+			const [_unused, recorder] = createTestMeterProvider();
+			await getActorHandle(actor);
+			deepStrictEqual(recorder.getMeasurements("activitypub.actor.discovery").length, 0);
+			deepStrictEqual(recorder.getMeasurements("activitypub.actor.discovery.duration").length, 0);
+			deepStrictEqual(recorder.getMeasurements("webfinger.lookup").length, 0);
+		});
+	} finally {
+		esm_default.removeRoutes();
+		esm_default.hardReset();
+	}
+});
 test("normalizeActorHandle()", () => {
 	deepStrictEqual(normalizeActorHandle("@foo@BAR.COM"), "@foo@bar.com");
 	deepStrictEqual(normalizeActorHandle("@BAZ@☃-⌘.com"), "@BAZ@☃-⌘.com");

package/dist-tests/lookup.test.mjs

@@ -1,7 +1,7 @@
 import { Temporal } from "@js-temporal/polyfill";
 globalThis.addEventListener = () => {};
 import { g as Object$1, h as Note, i as Collection, y as Person } from "./vocab-B0Z-tH4q.mjs";
-import { c as esm_default, i as isActor, o as name, s as version } from "./actor-DBM2eKvJ.mjs";
+import { c as esm_default, i as isActor, o as name, s as version } from "./actor-B38UQKg6.mjs";
 import { t as getTypeId } from "./type-Cf-vxmre.mjs";
 import { t as assertInstanceOf } from "./utils-CE8Dk5hm.mjs";
 import { createTestMeterProvider, createTestTracerProvider, mockDocumentLoader, test } from "@fedify/fixture";
@@ -186,6 +186,7 @@ async function lookupObjectInternal(identifier, options = {}) {
 		const jrd = await lookupWebFinger(identifier, {
 			userAgent: options.userAgent,
 			tracerProvider: options.tracerProvider,
+			meterProvider: options.meterProvider,
 			allowPrivateAddress: "allowPrivateAddress" in options && options.allowPrivateAddress === true,
 			signal: options.signal
 		});
@@ -781,6 +782,27 @@ test("lookupObject() records activitypub.object.lookup counter", {
 			});
 			deepStrictEqual(recorder.getMeasurements("activitypub.object.lookup").length, 0);
 		});
+		await t.step("propagates meterProvider into the nested webfinger.lookup", async () => {
+			esm_default.removeRoutes();
+			esm_default.get("begin:https://example.com/.well-known/webfinger", {
+				subject: "acct:johndoe@example.com",
+				links: [{
+					rel: "self",
+					href: "https://example.com/person",
+					type: "application/activity+json"
+				}]
+			});
+			const [meterProvider, recorder] = createTestMeterProvider();
+			await lookupObject("@johndoe@example.com", {
+				documentLoader: mockDocumentLoader,
+				contextLoader: mockDocumentLoader,
+				meterProvider
+			});
+			const webFingerCounter = recorder.getMeasurement("webfinger.lookup");
+			ok(webFingerCounter != null);
+			deepStrictEqual(webFingerCounter.attributes["webfinger.lookup.result"], "found");
+			deepStrictEqual(webFingerCounter.attributes["activitypub.remote.host"], "example.com");
+		});
 		await t.step("extracts host from a URL acct: instance", async () => {
 			esm_default.removeRoutes();
 			esm_default.get("begin:https://example.com/.well-known/webfinger", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/vocab",
-  "version": "2.3.0-dev.1131+553b59b8",
+  "version": "2.3.0-dev.1145+3fe78022",
   "homepage": "https://fedify.dev/",
   "repository": {
     "type": "git",
@@ -46,9 +46,9 @@
     "es-toolkit": "1.46.1",
     "jsonld": "^9.0.0",
     "pkijs": "^3.3.3",
-    "@fedify/vocab-tools": "2.3.0-dev.1131+553b59b8",
-    "@fedify/webfinger": "2.3.0-dev.1131+553b59b8",
-    "@fedify/vocab-runtime": "2.3.0-dev.1131+553b59b8"
+    "@fedify/vocab-tools": "2.3.0-dev.1145+3fe78022",
+    "@fedify/webfinger": "2.3.0-dev.1145+3fe78022",
+    "@fedify/vocab-runtime": "2.3.0-dev.1145+3fe78022"
   },
   "devDependencies": {
     "@types/node": "^22.17.0",

package/src/actor.test.ts

@@ -1,4 +1,4 @@
-import { test } from "@fedify/fixture";
+import { createTestMeterProvider, test } from "@fedify/fixture";
 import * as fc from "fast-check";
 import fetchMock from "fetch-mock";
 import {
@@ -192,6 +192,202 @@ test({
   },
 });
 
+test("getActorHandle() records activitypub.actor.discovery counter", {
+  permissions: { env: true, read: true },
+}, async (t) => {
+  fetchMock.spyGlobal();
+  try {
+    const actorId = new URL("https://foo.example.com/@john");
+    const actor = new Person({
+      id: actorId,
+      preferredUsername: "john",
+    });
+
+    await t.step("records result=resolved on a successful lookup", async () => {
+      fetchMock.removeRoutes();
+      fetchMock.get(
+        "begin:https://foo.example.com/.well-known/webfinger?",
+        {
+          body: { subject: "acct:johndoe@foo.example.com" },
+          headers: { "Content-Type": "application/jrd+json" },
+        },
+      );
+      const [meterProvider, recorder] = createTestMeterProvider();
+      const handle = await getActorHandle(actor, { meterProvider });
+      deepStrictEqual(handle, "@johndoe@foo.example.com");
+
+      const counters = recorder.getMeasurements(
+        "activitypub.actor.discovery",
+      );
+      deepStrictEqual(counters.length, 1);
+      deepStrictEqual(counters[0].type, "counter");
+      deepStrictEqual(counters[0].value, 1);
+      deepStrictEqual(
+        counters[0].attributes["activitypub.actor.discovery.result"],
+        "resolved",
+      );
+      deepStrictEqual(
+        counters[0].attributes["activitypub.remote.host"],
+        "foo.example.com",
+      );
+
+      const durations = recorder.getMeasurements(
+        "activitypub.actor.discovery.duration",
+      );
+      deepStrictEqual(durations.length, 1);
+      deepStrictEqual(durations[0].type, "histogram");
+      deepStrictEqual(
+        durations[0].attributes["activitypub.actor.discovery.result"],
+        "resolved",
+      );
+      ok(typeof durations[0].value === "number" && durations[0].value >= 0);
+    });
+
+    await t.step(
+      "records result=resolved when WebFinger is missing but preferredUsername fallback succeeds",
+      async () => {
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://foo.example.com/.well-known/webfinger?",
+          { status: 404 },
+        );
+        const [meterProvider, recorder] = createTestMeterProvider();
+        const handle = await getActorHandle(actor, { meterProvider });
+        deepStrictEqual(handle, "@john@foo.example.com");
+        const counter = recorder.getMeasurement("activitypub.actor.discovery");
+        ok(counter != null);
+        deepStrictEqual(
+          counter.attributes["activitypub.actor.discovery.result"],
+          "resolved",
+        );
+      },
+    );
+
+    await t.step(
+      "records result=not_found when neither WebFinger nor preferredUsername yields a handle",
+      async () => {
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://foo.example.com/.well-known/webfinger?",
+          { status: 404 },
+        );
+        const [meterProvider, recorder] = createTestMeterProvider();
+        await rejects(
+          () => getActorHandle(actorId, { meterProvider }),
+          TypeError,
+        );
+        const counter = recorder.getMeasurement("activitypub.actor.discovery");
+        ok(counter != null);
+        deepStrictEqual(
+          counter.attributes["activitypub.actor.discovery.result"],
+          "not_found",
+        );
+        deepStrictEqual(
+          counter.attributes["activitypub.remote.host"],
+          "foo.example.com",
+        );
+        const duration = recorder.getMeasurement(
+          "activitypub.actor.discovery.duration",
+        );
+        ok(duration != null);
+        deepStrictEqual(
+          duration.attributes["activitypub.actor.discovery.result"],
+          "not_found",
+        );
+      },
+    );
+
+    await t.step(
+      "records result=error when a malformed WebFinger alias throws TypeError",
+      async () => {
+        // The "[" byte makes `new URL("https://[/")` throw `TypeError`
+        // when getActorHandleInternal attempts to parse the alias host.
+        // This TypeError is a malformed-remote-data failure, not the
+        // "actor lacks information" sentinel, so the metric must record
+        // `error` rather than `not_found`.
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://foo.example.com/.well-known/webfinger?",
+          {
+            body: {
+              subject: "https://foo.example.com/@john",
+              aliases: ["acct:john@["],
+            },
+            headers: { "Content-Type": "application/jrd+json" },
+          },
+        );
+        const [meterProvider, recorder] = createTestMeterProvider();
+        await rejects(
+          () => getActorHandle(actorId, { meterProvider }),
+          TypeError,
+        );
+        const counter = recorder.getMeasurement(
+          "activitypub.actor.discovery",
+        );
+        ok(counter != null);
+        deepStrictEqual(
+          counter.attributes["activitypub.actor.discovery.result"],
+          "error",
+        );
+      },
+    );
+
+    await t.step(
+      "propagates meterProvider into the nested webfinger.lookup",
+      async () => {
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://foo.example.com/.well-known/webfinger?",
+          {
+            body: { subject: "acct:johndoe@foo.example.com" },
+            headers: { "Content-Type": "application/jrd+json" },
+          },
+        );
+        const [meterProvider, recorder] = createTestMeterProvider();
+        await getActorHandle(actor, { meterProvider });
+        const webFingerCounter = recorder.getMeasurement("webfinger.lookup");
+        ok(webFingerCounter != null);
+        deepStrictEqual(
+          webFingerCounter.attributes["webfinger.lookup.result"],
+          "found",
+        );
+      },
+    );
+
+    await t.step(
+      "omits measurements when no meterProvider is provided",
+      async () => {
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://foo.example.com/.well-known/webfinger?",
+          {
+            body: { subject: "acct:johndoe@foo.example.com" },
+            headers: { "Content-Type": "application/jrd+json" },
+          },
+        );
+        const [_unused, recorder] = createTestMeterProvider();
+        await getActorHandle(actor);
+        deepStrictEqual(
+          recorder.getMeasurements("activitypub.actor.discovery").length,
+          0,
+        );
+        deepStrictEqual(
+          recorder.getMeasurements("activitypub.actor.discovery.duration")
+            .length,
+          0,
+        );
+        deepStrictEqual(
+          recorder.getMeasurements("webfinger.lookup").length,
+          0,
+        );
+      },
+    );
+  } finally {
+    fetchMock.removeRoutes();
+    fetchMock.hardReset();
+  }
+});
+
 test("normalizeActorHandle()", () => {
   deepStrictEqual(normalizeActorHandle("@foo@BAR.COM"), "@foo@bar.com");
   deepStrictEqual(normalizeActorHandle("@BAZ@☃-⌘.com"), "@BAZ@☃-⌘.com");

package/src/actor.ts

@@ -1,11 +1,114 @@
 import type { GetUserAgentOptions } from "@fedify/vocab-runtime";
 import { lookupWebFinger } from "@fedify/webfinger";
-import { SpanStatusCode, trace, type TracerProvider } from "@opentelemetry/api";
+import {
+  type Attributes,
+  type Counter,
+  type Histogram,
+  type MeterProvider,
+  SpanStatusCode,
+  trace,
+  type TracerProvider,
+} from "@opentelemetry/api";
 import { domainToASCII, domainToUnicode } from "node:url";
 import metadata from "../deno.json" with { type: "json" };
 import { getTypeId } from "./type.ts";
 import { Application, Group, Organization, Person, Service } from "./vocab.ts";
 
+/**
+ * The terminal classification of a {@link getActorHandle} call, recorded as
+ * the `activitypub.actor.discovery.result` attribute on the
+ * `activitypub.actor.discovery` counter and
+ * `activitypub.actor.discovery.duration` histogram.
+ *
+ *  -  `resolved`: a handle was returned to the caller.
+ *  -  `not_found`: WebFinger did not yield a usable `acct:` alias and the
+ *     `preferredUsername` fallback could not run.  This corresponds to the
+ *     `TypeError("Actor does not have enough information…")` path.
+ *  -  `error`: any other thrown exception bubbled up from the lookup.
+ *
+ * Per-WebFinger-call failure detail (HTTP status, parse failure, network
+ * failure, etc.) lives on `webfinger.lookup` and is intentionally not
+ * duplicated here.
+ * @since 2.3.0
+ */
+export type ActorDiscoveryResult = "resolved" | "not_found" | "error";
+
+interface ActorDiscoveryInstruments {
+  discovery: Counter;
+  discoveryDuration: Histogram;
+}
+
+const ACTOR_DISCOVERY_HISTOGRAM_BUCKETS: ReadonlyArray<number> = [
+  5,
+  10,
+  25,
+  50,
+  75,
+  100,
+  250,
+  500,
+  750,
+  1000,
+  2500,
+  5000,
+  7500,
+  10000,
+];
+
+const actorDiscoveryInstruments = new WeakMap<
+  MeterProvider,
+  ActorDiscoveryInstruments
+>();
+
+function getActorDiscoveryInstruments(
+  meterProvider: MeterProvider,
+): ActorDiscoveryInstruments {
+  let instruments = actorDiscoveryInstruments.get(meterProvider);
+  if (instruments == null) {
+    const meter = meterProvider.getMeter(metadata.name, metadata.version);
+    instruments = {
+      discovery: meter.createCounter("activitypub.actor.discovery", {
+        description: "Actor handle discovery attempts via getActorHandle(), " +
+          "classified by terminal outcome.",
+        unit: "{discovery}",
+      }),
+      discoveryDuration: meter.createHistogram(
+        "activitypub.actor.discovery.duration",
+        {
+          description: "Duration of getActorHandle() actor discovery calls.",
+          unit: "ms",
+          advice: {
+            explicitBucketBoundaries: [...ACTOR_DISCOVERY_HISTOGRAM_BUCKETS],
+          },
+        },
+      ),
+    };
+    actorDiscoveryInstruments.set(meterProvider, instruments);
+  }
+  return instruments;
+}
+
+function getActorDiscoveryRemoteHost(
+  actor: Actor | URL,
+): string | undefined {
+  const id = actor instanceof URL ? actor : actor.id;
+  if (id == null) return undefined;
+  return id.hostname === "" ? undefined : id.hostname;
+}
+
+// Subclass of TypeError that preserves the documented `throws {TypeError}`
+// API contract while letting the actor-discovery metric distinguish the
+// "actor lacks enough information to derive a handle" terminal path from
+// other TypeError-shaped failures that can come from malformed remote data
+// (e.g. an alias that does not parse as a URL, or an invalid preferred
+// username that breaks normalizeActorHandle).
+class ActorHandleNotFoundError extends TypeError {
+  constructor() {
+    super("Actor does not have enough information to get the handle.");
+    this.name = "ActorHandleNotFoundError";
+  }
+}
+
 /**
  * Actor types are {@link Object} types that are capable of performing
  * activities.
@@ -101,6 +204,19 @@ export interface GetActorHandleOptions extends NormalizeActorHandleOptions {
    * @since 1.3.0
    */
   tracerProvider?: TracerProvider;
+
+  /**
+   * The OpenTelemetry meter provider used to record the
+   * `activitypub.actor.discovery` counter and
+   * `activitypub.actor.discovery.duration` histogram.  When set, the same
+   * meter provider is also forwarded to the nested WebFinger lookups so
+   * each discovery emits both the actor-discovery measurements and the
+   * underlying `webfinger.lookup` measurements.  If omitted, no
+   * measurements are emitted (the helper is opt-in to avoid touching the
+   * global meter provider for callers that do not use OpenTelemetry).
+   * @since 2.3.0
+   */
+  meterProvider?: MeterProvider;
 }
 
 /**
@@ -145,15 +261,36 @@ export async function getActorHandle(
         }
         span.setAttribute("activitypub.actor.type", getTypeId(actor).href);
       }
+      const meterProvider = options.meterProvider;
+      const start = meterProvider == null ? 0 : performance.now();
+      let result: ActorDiscoveryResult = "error";
       try {
-        return await getActorHandleInternal(actor, options);
+        const handle = await getActorHandleInternal(actor, options);
+        result = "resolved";
+        return handle;
       } catch (error) {
+        result = error instanceof ActorHandleNotFoundError
+          ? "not_found"
+          : "error";
         span.setStatus({
           code: SpanStatusCode.ERROR,
           message: String(error),
         });
         throw error;
       } finally {
+        if (meterProvider != null) {
+          const attributes: Attributes = {
+            "activitypub.actor.discovery.result": result,
+          };
+          const host = getActorDiscoveryRemoteHost(actor);
+          if (host != null) attributes["activitypub.remote.host"] = host;
+          const instruments = getActorDiscoveryInstruments(meterProvider);
+          instruments.discovery.add(1, attributes);
+          instruments.discoveryDuration.record(
+            Math.max(0, performance.now() - start),
+            attributes,
+          );
+        }
         span.end();
       }
     },
@@ -169,6 +306,7 @@ async function getActorHandleInternal(
     const result = await lookupWebFinger(actorId, {
       userAgent: options.userAgent,
       tracerProvider: options.tracerProvider,
+      meterProvider: options.meterProvider,
     });
     if (result != null) {
       const aliases = [...(result.aliases ?? [])];
@@ -184,6 +322,7 @@ async function getActorHandleInternal(
               alias,
               options.userAgent,
               options.tracerProvider,
+              options.meterProvider,
             )
           ) {
             continue;
@@ -202,9 +341,7 @@ async function getActorHandleInternal(
       options,
     );
   }
-  throw new TypeError(
-    "Actor does not have enough information to get the handle.",
-  );
+  throw new ActorHandleNotFoundError();
 }
 
 async function verifyCrossOriginActorHandle(
@@ -212,8 +349,13 @@ async function verifyCrossOriginActorHandle(
   alias: string,
   userAgent: GetUserAgentOptions | string | undefined,
   tracerProvider: TracerProvider | undefined,
+  meterProvider: MeterProvider | undefined,
 ): Promise<boolean> {
-  const response = await lookupWebFinger(alias, { userAgent, tracerProvider });
+  const response = await lookupWebFinger(alias, {
+    userAgent,
+    tracerProvider,
+    meterProvider,
+  });
   if (response == null) return false;
   for (const alias of response.aliases ?? []) {
     if (new URL(alias).href === actorId) return true;

package/src/lookup.test.ts

@@ -811,6 +811,42 @@ test("lookupObject() records activitypub.object.lookup counter", {
       },
     );
 
+    await t.step(
+      "propagates meterProvider into the nested webfinger.lookup",
+      async () => {
+        fetchMock.removeRoutes();
+        fetchMock.get(
+          "begin:https://example.com/.well-known/webfinger",
+          {
+            subject: "acct:johndoe@example.com",
+            links: [
+              {
+                rel: "self",
+                href: "https://example.com/person",
+                type: "application/activity+json",
+              },
+            ],
+          },
+        );
+        const [meterProvider, recorder] = createTestMeterProvider();
+        await lookupObject("@johndoe@example.com", {
+          documentLoader: mockDocumentLoader,
+          contextLoader: mockDocumentLoader,
+          meterProvider,
+        });
+        const webFingerCounter = recorder.getMeasurement("webfinger.lookup");
+        ok(webFingerCounter != null);
+        deepStrictEqual(
+          webFingerCounter.attributes["webfinger.lookup.result"],
+          "found",
+        );
+        deepStrictEqual(
+          webFingerCounter.attributes["activitypub.remote.host"],
+          "example.com",
+        );
+      },
+    );
+
     await t.step(
       "extracts host from a URL acct: instance",
       async () => {

package/src/lookup.ts

@@ -286,6 +286,7 @@ async function lookupObjectInternal(
     const jrd = await lookupWebFinger(identifier, {
       userAgent: options.userAgent,
       tracerProvider: options.tracerProvider,
+      meterProvider: options.meterProvider,
       allowPrivateAddress: "allowPrivateAddress" in options &&
         options.allowPrivateAddress === true,
       signal: options.signal,