@intentius/chant-lexicon-otel 0.124.46 → 0.124.48

package/src/import/roundtrip.test.ts

@@ -217,6 +217,22 @@ describe("YAML -> TypeScript -> YAML", () => {
     expect(out.warnings).toEqual([]);
   });
 
+  test("a clickhouse exporter imports to the typed class (#4397)", async () => {
+    const out = await expectRoundTrip(read("clickhouse.yaml"));
+    expect(out.source).toContain("new ClickHouseExporter(");
+    expect(out.source).not.toContain("defineComponent");
+    expect(out.source).toContain("create_schema: false");
+    expect(out.warnings).toEqual([]);
+  });
+
+  test("collector-contrib v0.130.0: the clickhouse exporter's own example (#4397)", async () => {
+    // fluentforward is not a built-in, so it alone goes through defineComponent; the example's literal password is reported.
+    const out = await expectRoundTrip(read("upstream", "clickhouse-exporter.yaml"), { lintRules: ["OTEL002"] });
+    expect(out.source).toContain("new ClickHouseExporter(");
+    expect(out.source).toMatch(/type: "fluentforward"/);
+    expect(out.source).not.toMatch(/type: "clickhouse"/);
+  });
+
   test("the collector configs of examples/agent-observability", async () => {
     for (const file of ["agent-observability-agent.yaml", "agent-observability-gateway.yaml"]) {
       await expectRoundTrip(read(file));

package/src/import/testdata/clickhouse.yaml

@@ -0,0 +1,37 @@
+# A collector writing every signal to ClickHouse tables the sql lexicon manages (#4397).
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+processors:
+  batch: {}
+exporters:
+  clickhouse:
+    endpoint: tcp://clickhouse:9000
+    database: otel
+    username: ${env:CLICKHOUSE_USER}
+    password: ${env:CLICKHOUSE_PASSWORD}
+    create_schema: false
+    logs_table_name: app_logs
+    metrics_tables:
+      exponential_histogram:
+        name: app_exp_histogram
+    sending_queue:
+      queue_size: 1000
+    retry_on_failure:
+      enabled: true
+service:
+  pipelines:
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [clickhouse]
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [clickhouse]
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [clickhouse]

package/src/import/testdata/fixtures.ts

@@ -183,6 +183,20 @@ export function everyBuiltin(): Declarable[] {
     trace: { attribute_mappings: [{ key: "http.route", replacement: "/http/route" }] },
     log: { default_log_name: "otel" },
   });
+  const clickhouse = new c.ClickHouseExporter({
+    endpoint: "tcp://clickhouse:9000",
+    database: "otel",
+    username: "${env:CLICKHOUSE_USER}",
+    password: "${env:CLICKHOUSE_PASSWORD}",
+    create_schema: false,
+    ttl: "72h",
+    logs_table_name: "app_logs",
+    metrics_tables: { gauge: { name: "app_gauge" }, exponential_histogram: { name: "app_exp_histogram" } },
+    async_insert: true,
+    compress: "zstd",
+    timeout: "10s",
+    sending_queue: { queue_size: 1000 },
+  });
   const loadbalancing = new c.LoadBalancingExporter({
     routing_key: "service",
     protocol: { otlp: { timeout: "1s", tls: { insecure: true } } },
@@ -266,6 +280,7 @@ export function everyBuiltin(): Declarable[] {
     debug,
     prometheusOut,
     googlecloud,
+    clickhouse,
     loadbalancing,
     spanmetrics,
     servicegraph,
@@ -290,13 +305,13 @@ export function everyBuiltin(): Declarable[] {
       signal: "metrics",
       receivers: [otlp, prometheusIn, hostmetrics, cluster, kubelet, spanmetrics, servicegraph, count, sum, signalToMetrics],
       processors: [memoryLimiter, filter, deltaToCumulative, batch],
-      exporters: [prometheusOut, otlphttp],
+      exporters: [prometheusOut, otlphttp, clickhouse],
     }),
     new Pipeline({
       signal: "logs",
       receivers: [otlp, filelog],
       processors: [memoryLimiter, redaction, batch],
-      exporters: [otlphttp, debug, signalToMetrics],
+      exporters: [otlphttp, debug, signalToMetrics, clickhouse],
     }),
     new Service({
       extensions: [health, zpages, pprof, leaderElector],

package/src/import/testdata/upstream/clickhouse-exporter.yaml

@@ -0,0 +1,60 @@
+# Vendored from opentelemetry-collector-contrib v0.130.0 (Apache-2.0), unchanged below this header:
+# https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.130.0/exporter/clickhouseexporter/example/otel-collector-config.yml
+
+receivers:
+  fluentforward:
+    endpoint: 0.0.0.0:24224
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+processors:
+  batch:
+    send_batch_size: 100000
+    timeout: 5s
+  memory_limiter:
+    check_interval: 2s
+    limit_mib: 1800
+    spike_limit_mib: 500
+  resourcedetection/system:
+    detectors: [ "system" ]
+    system:
+      hostname_sources: [ "os" ]
+  resource:
+    attributes:
+      - key: service.name
+        value: "serviceName"
+        action: upsert
+exporters:
+  clickhouse:
+    endpoint: tcp://clickhouse:9000
+    database: otel
+    logs_table_name: otel_logs
+    traces_table_name: otel_traces
+    ttl: 12h
+    timeout: 10s
+    sending_queue:
+      queue_size: 100
+    retry_on_failure:
+      enabled: true
+      initial_interval: 5s
+      max_interval: 30s
+      max_elapsed_time: 300s
+    username: default
+    password: default
+extensions:
+  health_check:
+  pprof:
+  zpages:
+
+service:
+  extensions: [ pprof, zpages, health_check ]
+  pipelines:
+    logs:
+      receivers: [ fluentforward, otlp ]
+      processors: [ memory_limiter, resourcedetection/system, resource, batch ]
+      exporters: [ clickhouse ]
+    traces:
+      receivers: [ otlp ]
+      processors: [ memory_limiter, resourcedetection/system, resource, batch ]
+      exporters: [ clickhouse ]

package/src/index.ts

@@ -7,6 +7,48 @@ export { otelSerializer } from "./serializer";
 // Built-in components and their config types
 export * from "./components";
 
+// The config types generated from upstream config.schema.yaml at COLLECTOR_PIN
+// (#3361), before any hand-written overlay. Each built-in's `<Class>Config`
+// builds on its `<Class>SchemaConfig`.
+export type {
+  AttributesProcessorSchemaConfig,
+  BatchProcessorSchemaConfig,
+  CountConnectorSchemaConfig,
+  DebugExporterSchemaConfig,
+  DeltaToCumulativeProcessorSchemaConfig,
+  FileLogReceiverSchemaConfig,
+  FilterProcessorSchemaConfig,
+  GoogleCloudExporterSchemaConfig,
+  HealthCheckExtensionSchemaConfig,
+  HostMetricsReceiverSchemaConfig,
+  K8sAttributesProcessorSchemaConfig,
+  K8sClusterReceiverSchemaConfig,
+  K8sLeaderElectorExtensionSchemaConfig,
+  KubeletStatsReceiverSchemaConfig,
+  LoadBalancingExporterSchemaConfig,
+  MemoryLimiterProcessorSchemaConfig,
+  OtlpExporterSchemaConfig,
+  OtlpHttpExporterSchemaConfig,
+  OtlpReceiverSchemaConfig,
+  PprofExtensionSchemaConfig,
+  ProbabilisticSamplerProcessorSchemaConfig,
+  PrometheusExporterSchemaConfig,
+  PrometheusReceiverSchemaConfig,
+  RedactionProcessorSchemaConfig,
+  ResourceDetectionProcessorSchemaConfig,
+  ResourceProcessorSchemaConfig,
+  RoutingConnectorSchemaConfig,
+  ServiceGraphConnectorSchemaConfig,
+  SignalToMetricsConnectorSchemaConfig,
+  SpanMetricsConnectorSchemaConfig,
+  SumConnectorSchemaConfig,
+  TailSamplingProcessorSchemaConfig,
+  TransformProcessorSchemaConfig,
+  ZPagesExtensionSchemaConfig,
+} from "./generated/index";
+export { coverageReport, formatCoverage, type OtelCoverageReport, type DistributionCoverage } from "./coverage";
+export { OTELCOL_CONTRIB_VERSION, OTELCOL_K8S_VERSION, OTEL_SPEC_PIN, type OtelSpecPin } from "./spec/pin";
+
 // Pipelines and the service block
 export {
   Pipeline,
@@ -168,6 +210,8 @@ export {
   type SpanMetricsNames,
   type SpanMetricsNamingConfig,
   type PrometheusNaming,
+  type PrometheusTranslationStrategy,
+  exporterNaming,
   promSelector,
   promSumRate,
   promErrorRatio,
@@ -188,3 +232,28 @@ export {
 // `@intentius/chant-lexicon-otel/op/activities`.
 export { otelcolValidate, otelcolComponents, collectorHealthObserve, collectorAudit } from "./op/builders";
 export { CollectorAuditOp, type CollectorAuditOpConfig, type CollectorAuditOpResources } from "./op/audit-op";
+
+// A custom collector built with ocb (#3374): the builder manifest as an
+// entity, the `ocb-build` build verb, and the check that a config uses only
+// what the distribution builds (OTEL128).
+export {
+  Distribution,
+  DISTRIBUTION_TYPE,
+  DISTRIBUTION_MANIFEST_FILE,
+  BUILTIN_MODULES,
+  isDistributionEntity,
+  distributionManifest,
+  distributionYaml,
+  distributionComponents,
+  distributionIssues,
+  componentModule,
+  moduleComponentType,
+  type DistributionProps,
+  type DistributionDist,
+  type DistributionModule,
+  type DistributionComponent,
+  type DistributionEntity,
+  type DistributionComponents,
+} from "./distribution";
+export { otelCapabilityPlugin, OTEL_VERB_FAMILIES, ocbBuild } from "./build/capability-plugin";
+export { createOcbBuildCapability, ocbBuildCapability, ocbOutputPath, type OcbBuildInput, type OcbBuildOutput } from "./build/ocb-build";

package/src/init-templates.ts

@@ -78,8 +78,8 @@ const retry: RetrySettings = { enabled: true, max_elapsed_time: "300s" };
 const gateway = new OtlpExporter({ name: "gateway", endpoint: "otel-gateway.observability.svc:4317", tls: inCluster, retry_on_failure: retry });
 
 // Resource attributes (k8s.namespace.name, k8s.pod.name, ...) become metric labels.
-const asLabels = { enabled: true };
-const scrape = new PrometheusExporter({ endpoint: "0.0.0.0:8889", resource_to_telemetry_conversion: asLabels });
+const asLabels = { included: ["*"] };
+const scrape = new PrometheusExporter({ endpoint: "0.0.0.0:8889", resource_constant_labels: asLabels });
 
 export { gateway, scrape };
 `;

package/src/lint/audit-catalog.ts

@@ -5,6 +5,9 @@
  * OTEL101-OTEL106, OTEL112-OTEL117 and OTEL119-OTEL127 read the emitted collector YAML, so they are
  * `yamlBased`. OTEL118 reads it too, but only in a build that stamps
  * telemetry attribution, so it is not.
+ * OTEL128 reads both: the emitted config and the declared `Distribution`.
+ * OTEL129 reads both too: the emitted config and the sql lexicon's declared
+ * ClickHouse tables.
  * OTEL107-OTEL109 read the declared entities (a component's definition, its
  * schema pin), which a standalone YAML file does not carry, so they are
  * constructed with `yamlBased: false`. The two source-level lint rules are
@@ -233,4 +236,16 @@ export const otelAuditCatalog: Record<string, RuleMeta> = {
     "Name detectors as the processor registers them (elastic_beanstalk, not elasticbeanstalk), or remove the entry.",
     { category: "correctness" },
   ),
+  OTEL128: entityRule(
+    "OTEL128",
+    "correctness",
+    "Collector config uses a component the declared Distribution does not build",
+    "Add the component to the Distribution's list for its kind, or remove it from the collector config.",
+  ),
+  OTEL129: entityRule(
+    "OTEL129",
+    "correctness",
+    "A clickhouse exporter writes a table or column the sql build in the same root does not declare",
+    "Declare the exporter's tables with OtelTables from the sql lexicon, or point the exporter's table names at declared tables, and set create_schema: false.",
+  ),
 };

package/src/lint/post-synth/index.ts

@@ -25,6 +25,8 @@ import { otel124 } from "./otel124";
 import { otel125 } from "./otel125";
 import { otel126 } from "./otel126";
 import { otel127 } from "./otel127";
+import { otel128 } from "./otel128";
+import { otel129 } from "./otel129";
 
 export const postSynthChecks: PostSynthCheck[] = [
   otel101,
@@ -52,4 +54,6 @@ export const postSynthChecks: PostSynthCheck[] = [
   otel125,
   otel126,
   otel127,
+  otel128,
+  otel129,
 ];

package/src/lint/post-synth/otel-helpers.ts

@@ -68,7 +68,7 @@ export function collectorConfigs(ctx: PostSynthContext): FoundCollectorConfig[]
   return out;
 }
 
-function toDiagnostic(issue: CollectorIssue, found?: Omit<FoundCollectorConfig, "config">): PostSynthDiagnostic {
+export function toDiagnostic(issue: CollectorIssue, found?: Omit<FoundCollectorConfig, "config">): PostSynthDiagnostic {
   const where = found?.configMap
     ? describeConfigMapConfig(found.configMap)
     : found?.operator

package/src/lint/post-synth/otel119.ts

@@ -1,7 +1,7 @@
 /**
  * OTEL119: A collector config sets a field deprecated at or before the pinned release
  *
- * `invert_match: true` in a `tail_sampling` policy (inverted decisions are deprecated in collector-contrib v0.126.0 for a `drop` policy), `service.telemetry.metrics.address` (deprecated in collector v0.111.0 for `readers`), and `dimensions_cache_size` on `spanmetrics` (deprecated in collector-contrib v0.125.0 for `aggregation_cardinality_limit`). The collector still reads each at v0.130.0, and a later release drops it.
+ * `invert_match: true` in a `tail_sampling` policy (inverted decisions are deprecated in collector-contrib v0.126.0 for a `drop` policy, and v0.155.0 removed the gate that kept them), `service.telemetry.metrics.address` (deprecated in collector v0.111.0 for `readers`), and `dimensions_cache_size` on `spanmetrics` (deprecated in collector-contrib v0.125.0 for `aggregation_cardinality_limit`). The collector still parses each at v0.162.0, and a later release drops it.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/otel125.ts

@@ -1,7 +1,7 @@
 /**
  * OTEL125: A pipeline sends to a remote otlp or otlphttp exporter without batching
  *
- * No `batch` processor in the pipeline, and the `otlp` or `otlphttp` exporter (non-loopback endpoint) sets no `sending_queue.batch`. At v0.130.0 neither exporter batches by default, so each small request goes out on its own. Other exporters may batch themselves and are not checked.
+ * No `batch` processor in the pipeline, and the `otlp` or `otlphttp` exporter (non-loopback endpoint) sets no `sending_queue.batch`. At v0.162.0 neither exporter batches by default, so each small request goes out on its own. Other exporters may batch themselves and are not checked.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/otel126.ts

@@ -1,7 +1,7 @@
 /**
  * OTEL126: k8sattributes extracts a metadata field it does not support
  *
- * Each name in a `k8sattributes` processor's `extract.metadata` must be one `Config.Validate` accepts at collector-contrib v0.130.0 (`K8S_ATTRIBUTES_METADATA`); the collector refuses any other.
+ * Each name in a `k8sattributes` processor's `extract.metadata` must be one `Config.Validate` accepts at collector-contrib v0.162.0 (`K8S_ATTRIBUTES_METADATA`); the collector refuses any other.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/otel127.ts

@@ -1,7 +1,7 @@
 /**
  * OTEL127: resourcedetection lists a detector that does not exist
  *
- * Each name in a started `resourcedetection` processor's `detectors` must be one the processor registers at collector-contrib v0.130.0 (`RESOURCE_DETECTORS`); any other fails the processor's build and the collector exits.
+ * Each name in a started `resourcedetection` processor's `detectors` must be one the processor registers at collector-contrib v0.162.0 (`RESOURCE_DETECTORS`); any other fails the processor's build and the collector exits.
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";

package/src/lint/post-synth/otel128.ts

@@ -0,0 +1,22 @@
+/**
+ * OTEL128: The collector config uses a component the declared Distribution does not build
+ *
+ * When a project declares a `Distribution` (an ocb builder manifest), every component a collector config declares must be one the distribution builds; a collector built from it fails at start with "unknown type" otherwise. A project without a `Distribution` is not checked.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { distributionIssues, isDistributionEntity } from "../../distribution";
+import { collectorConfigs, toDiagnostic } from "./otel-helpers";
+
+export const otel128: PostSynthCheck = {
+  id: "OTEL128",
+  description: "The collector config uses a component the declared Distribution does not build",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const dist = [...(ctx.entities?.values() ?? [])].find(isDistributionEntity);
+    if (!dist) return [];
+    return collectorConfigs(ctx).flatMap(({ config, ...found }) =>
+      distributionIssues(config, dist).map((i) => toDiagnostic(i, found)),
+    );
+  },
+};

package/src/lint/post-synth/otel129.ts

@@ -0,0 +1,99 @@
+/**
+ * OTEL129: A clickhouse exporter writes a table the sql build in the same root does not declare
+ *
+ * When the build root also declares ClickHouse tables with the sql lexicon, every table a `clickhouse` exporter writes (for the signals whose pipelines use it) must be one of them, in the database the exporter writes to, with every column the exporter's insert statement names. A renamed or dropped table fails here instead of at the exporter's first insert. When `create_schema` is true (the exporter's default) for tables the build declares, it warns: the exporter would run its own `CREATE TABLE IF NOT EXISTS` beside the sql lexicon's plan. A build root with no sql ClickHouse tables is not checked. Sees one build root at a time (#1939); across workspace members the otel lexicon's workspace links check the same tables (#3931).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import type { Declarable } from "@intentius/chant/declarable";
+import { clickhouseExportersOf } from "../../clickhouse-tables";
+import { collectorConfigs } from "./otel-helpers";
+
+/** The sql lexicon's ClickHouse table entity type, matched by name so otel needs no dependency on the sql lexicon. */
+const CLICKHOUSE_TABLE = "ClickHouse::Table";
+
+interface DeclaredTable {
+  columns: Set<string>;
+}
+
+/** Every ClickHouse table the build declares, by `database.name`. */
+export function declaredClickHouseTables(entities: Iterable<Declarable>): Map<string, DeclaredTable> {
+  const out = new Map<string, DeclaredTable>();
+  for (const e of entities) {
+    if (e.entityType !== CLICKHOUSE_TABLE) continue;
+    const props = (e as unknown as { props?: { name?: unknown; database?: unknown; columns?: unknown } }).props;
+    if (typeof props?.name !== "string") continue;
+    const database = typeof props.database === "string" && props.database !== "" ? props.database : "default";
+    const columns = new Set<string>();
+    for (const c of Array.isArray(props.columns) ? props.columns : []) {
+      const name = (c as { name?: unknown })?.name;
+      if (typeof name === "string") columns.add(name);
+    }
+    out.set(`${database}.${props.name}`, { columns });
+  }
+  return out;
+}
+
+/** A column the insert names is declared as itself, or as the flattened fields of a Nested column (`Events.Timestamp`). */
+function hasColumn(declared: Set<string>, column: string): boolean {
+  if (declared.has(column)) return true;
+  for (const c of declared) if (c.startsWith(`${column}.`)) return true;
+  return false;
+}
+
+export const otel129: PostSynthCheck = {
+  id: "OTEL129",
+  description: "A clickhouse exporter writes a table the sql build in the same root does not declare",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const declared = declaredClickHouseTables(ctx.entities?.values() ?? []);
+    if (declared.size === 0) return [];
+    const known = [...declared.keys()].sort();
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const { config } of collectorConfigs(ctx)) {
+      for (const exp of clickhouseExportersOf(config)) {
+        const createsDeclared: string[] = [];
+        for (const t of exp.tables) {
+          const qualified = `${exp.database}.${t.name}`;
+          const table = declared.get(qualified);
+          if (!table) {
+            diagnostics.push({
+              checkId: "OTEL129",
+              severity: "error",
+              message:
+                `exporter ${exp.id} writes ${t.signal} to ${qualified} (${t.key}), which the sql build does not declare. ` +
+                `Declare it (OtelTables from @intentius/chant-lexicon-sql/clickhouse declares the exporter's tables) or point ${t.key} at a declared table. ` +
+                `Declared ClickHouse tables: ${known.join(", ")}`,
+              entity: exp.id,
+              lexicon: "otel",
+            });
+            continue;
+          }
+          const missing = t.columns.filter((c) => !hasColumn(table.columns, c));
+          if (missing.length > 0) {
+            diagnostics.push({
+              checkId: "OTEL129",
+              severity: "error",
+              message: `exporter ${exp.id} inserts ${t.signal} into ${qualified} with column${missing.length === 1 ? "" : "s"} ${missing.join(", ")}, which the declared table does not have; the insert would fail`,
+              entity: exp.id,
+              lexicon: "otel",
+            });
+          }
+          createsDeclared.push(qualified);
+        }
+        if (exp.createSchema && createsDeclared.length > 0) {
+          diagnostics.push({
+            checkId: "OTEL129",
+            severity: "warning",
+            message:
+              `exporter ${exp.id} has create_schema true (the default), so at start it runs CREATE TABLE IF NOT EXISTS for ${createsDeclared.join(", ")}, which the sql build declares. ` +
+              `Set create_schema: false so the sql lexicon alone manages them`,
+            entity: exp.id,
+            lexicon: "otel",
+          });
+        }
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lsp/completions.ts

@@ -1,6 +1,7 @@
 import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconCompletions } from "@intentius/chant/lsp/lexicon-providers";
 import { lexiconRegistry } from "../catalog";
+import { propertiesAt, propertyMarkdown, propertyPosition } from "./properties";
 
 let cachedIndex: LexiconIndex | null = null;
 
@@ -9,7 +10,35 @@ function getIndex(): LexiconIndex {
   return cachedIndex;
 }
 
-/** Completions for the otel entity classes: the built-in components, Pipeline and Service. */
+/** The text of `content` before the cursor. */
+export function textBefore(content: string, position: { line: number; character: number }): string {
+  const lines = content.split("\n");
+  return [...lines.slice(0, position.line), (lines[position.line] ?? "").slice(0, position.character)].join("\n");
+}
+
+/**
+ * Completions for the otel entity classes after `new`, and inside a built-in's
+ * constructor, the config properties at the cursor's depth, with upstream's
+ * descriptions (#3361).
+ */
 export function completions(ctx: CompletionContext): CompletionItem[] {
+  if (ctx?.content && ctx.position && !/\bnew\s+\w*$/.test(ctx.linePrefix ?? "")) {
+    const position = propertyPosition(textBefore(ctx.content, ctx.position));
+    const props = position && propertiesAt(position);
+    if (position && props) {
+      const prefix = (ctx.wordAtCursor ?? "").toLowerCase();
+      return Object.entries(props)
+        .filter(([name]) => name.toLowerCase().startsWith(prefix))
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, doc]) => ({
+          label: name,
+          insertText: name,
+          kind: "property" as const,
+          detail: doc.type,
+          documentation: propertyMarkdown(name, doc, position.className),
+          ...(doc.deprecated ? { deprecated: true } : {}),
+        }));
+    }
+  }
   return lexiconCompletions(ctx, getIndex(), "OpenTelemetry Collector entity");
 }

package/src/lsp/hover.ts

@@ -2,6 +2,8 @@ import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
 import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
 import { BUILTIN_CATALOG, lexiconRegistry } from "../catalog";
 import { COLLECTOR_PIN } from "../define";
+import { propertiesAt, propertyMarkdown, propertyPosition } from "./properties";
+import { textBefore } from "./completions";
 
 let cachedIndex: LexiconIndex | null = null;
 
@@ -10,9 +12,18 @@ function getIndex(): LexiconIndex {
   return cachedIndex;
 }
 
-/** Hover for otel entity classes: what the component does and its collector id. */
+/**
+ * Hover for otel entity classes (what the component does and its collector
+ * id), and for a config property inside a built-in's constructor (upstream's
+ * description, #3361).
+ */
 export function hover(ctx: HoverContext): HoverInfo | undefined {
-  return lexiconHover(ctx, getIndex(), resourceHover);
+  const entity = lexiconHover(ctx, getIndex(), resourceHover);
+  if (entity) return entity;
+  if (!ctx?.content || !ctx.position || !ctx.word) return undefined;
+  const position = propertyPosition(textBefore(ctx.content, ctx.position));
+  const doc = position && propertiesAt(position)?.[ctx.word];
+  return position && doc ? { contents: propertyMarkdown(ctx.word, doc, position.className) } : undefined;
 }
 
 function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
@@ -23,7 +34,7 @@ function resourceHover(className: string, entry: LexiconEntry): HoverInfo | unde
     lines.push(
       "",
       `Collector id \`${cat.type}\`, or \`${cat.type}/<name>\` with \`name\` set. ` +
-        `Config typed against ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}.`,
+        `Config typed from upstream config.schema.yaml at ${COLLECTOR_PIN.source} ${COLLECTOR_PIN.version}.`,
     );
   }
   return { contents: lines.join("\n") };

package/src/lsp/properties.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, test } from "vitest";
+import { propertiesAt, propertyPosition, setPropertyTrees } from "./properties";
+import { completions } from "./completions";
+import { hover } from "./hover";
+
+const TREES = {
+  OtlpReceiver: {
+    protocols: {
+      type: "object",
+      description: "Protocols is the configuration for the supported protocols.",
+      properties: {
+        grpc: { type: "object", properties: { endpoint: { type: "string", description: "Endpoint to listen on." } } },
+        http: { type: "object" },
+      },
+    },
+  },
+  TailSamplingProcessor: {
+    decision_wait: { type: "duration" },
+    policies: { type: "object[]", properties: { name: { type: "string" }, latency: { type: "object", properties: { threshold_ms: { type: "number" } } } } },
+    num_traces: { type: "number", deprecated: true },
+  },
+};
+
+afterEach(() => setPropertyTrees(undefined));
+
+describe("property positions", () => {
+  test("the keys of the objects around the cursor, through lists", () => {
+    expect(propertyPosition("new OtlpReceiver({ ")).toEqual({ className: "OtlpReceiver", path: [] });
+    expect(propertyPosition("new OtlpReceiver({ protocols: { grpc: { ")).toEqual({ className: "OtlpReceiver", path: ["protocols", "grpc"] });
+    expect(propertyPosition('new OtlpReceiver({ protocols: { http: {}, "grpc": { ')).toEqual({ className: "OtlpReceiver", path: ["protocols", "grpc"] });
+    expect(propertyPosition('new TailSamplingProcessor({ policies: [{ name: "a" }, { latency: { ')).toEqual({
+      className: "TailSamplingProcessor",
+      path: ["policies", "latency"],
+    });
+    expect(propertyPosition("new OtlpReceiver({ protocols: {} });\nconst x = { ")).toBeUndefined();
+    expect(propertyPosition("const x = { ")).toBeUndefined();
+  });
+
+  test("the properties at a path", () => {
+    setPropertyTrees(TREES);
+    expect(Object.keys(propertiesAt({ className: "OtlpReceiver", path: ["protocols"] })!)).toEqual(["grpc", "http"]);
+    expect(propertiesAt({ className: "OtlpReceiver", path: ["nope"] })).toBeUndefined();
+  });
+});
+
+describe("completion and hover", () => {
+  const at = (content: string, word = "") => {
+    const lines = content.split("\n");
+    return { uri: "file:///c.ts", content, position: { line: lines.length - 1, character: lines[lines.length - 1].length }, wordAtCursor: word, linePrefix: lines[lines.length - 1] };
+  };
+
+  test("offers the properties at the cursor's depth, with upstream's description", () => {
+    setPropertyTrees(TREES);
+    const items = completions(at("const r = new OtlpReceiver({ protocols: { grpc: { "));
+    expect(items.map((i) => i.label)).toEqual(["endpoint"]);
+    expect(items[0].documentation).toContain("Endpoint to listen on.");
+    const top = completions(at("new TailSamplingProcessor({ num", "num"));
+    expect(top).toEqual([expect.objectContaining({ label: "num_traces", detail: "number", deprecated: true })]);
+  });
+
+  test("still offers the classes after new", () => {
+    setPropertyTrees(TREES);
+    expect(completions(at("const r = new Otlp", "Otlp")).map((i) => i.label)).toContain("OtlpReceiver");
+  });
+
+  test("hovers a property with its description", () => {
+    setPropertyTrees(TREES);
+    const content = "new OtlpReceiver({ protocols";
+    const info = hover({ uri: "file:///c.ts", content, position: { line: 0, character: 19 }, word: "protocols", lineText: content });
+    expect(info?.contents).toContain("Protocols is the configuration for the supported protocols.");
+  });
+});