Hyphen
Log In

SigNoz

Learn how to integrate SigNoz Cloud or self-hosted instances with Hyphen to query application logs and Kubernetes telemetry.

1. Sign into your SigNoz instance

Use the SigNoz Cloud or self-hosted instance that receives your app and Kubernetes telemetry. Hyphen requires an instance with the v5 query API (/api/v5/query_range).

For SigNoz Cloud, set apiBaseUrl to your instance's HTTPS URL, such as https://your-instance.signoz.cloud. SigNoz's Logs API uses the instance URL for queries. Hyphen accepts Cloud instance URLs on signoz.cloud or signoz.io without a custom port.

For self-hosted SigNoz, use an HTTP(S) endpoint reachable by Hyphen, such as https://observability.example.com. Private-network and localhost endpoints are not supported by the hosted integration.

2. Generate an API key

Create a SigNoz service account and API key:

  1. Open Settings > Service Accounts and create or select a service account.
  2. Assign a role that can read the logs and metrics Hyphen will query, such as signoz-viewer.
  3. Open the account's Keys tab and click Add Key.
  4. Name the key, choose an expiration if needed, and copy it when it is created.

The key needs query access to the instance's telemetry. See SigNoz's read-only API key guide for viewer permissions. Keep the key secure and replace it in Hyphen when it expires or is rotated.

3. Connect SigNoz

In Hyphen's Integrations area, select SigNoz, choose Cloud or self-hosted, and enter the API base URL and API key.

Enter only the base URL in apiBaseUrl; Hyphen appends /api/v5/query_range. If your UI uses a separate address, enter it in the optional uiBaseUrl field. URLs must not contain embedded credentials, query parameters, or fragments. The API endpoint must respond directly; redirects are not followed.

Hyphen validates the key and query API with a log query. An empty result is allowed, so successful setup does not guarantee that app or cluster telemetry has arrived.

Configuration

Field Type Description
hosting string (required) cloud or selfHosted.
apiBaseUrl string (required) Base URL of the SigNoz instance serving the v5 query API.
uiBaseUrl string Optional base URL for the SigNoz UI.
apiKey string (required) API key supplied during setup.
secrets object Built during integration setup containing:
  apiKey string Stored key used to authenticate future requests.

Connections

Table of Contents

APM

APM connections map a Hyphen app to existing SigNoz services so Hyphen Agent can query its logs for the selected environment.

Before You Connect

  • Send app logs to the connected SigNoz instance with the service.name resource attribute.
  • If a service name is shared across namespaces, include service.namespace and specify it in the connection.
  • For a service shared across environments, emit an environment attribute whose values match the Hyphen project environment identifiers, such as production.

Configuration

Field Type Description
mode string (required) sharedByEnvironmentAttribute or perEnvironment.
entityName string Exact service.name for shared mode.
entityNamespace string Optional service.namespace for shared mode or an individual environment mapping.
environmentAttribute string Required in shared mode. The emitted attribute used to distinguish environments, such as deployment.environment.name.
environments object Required in per-environment mode. Maps every project environment identifier to an object containing entityName and optionally entityNamespace.

Connection Input

Provide a JSON service mapping when connecting APM for the app.

For one service shared across environments:

{
  "mode": "sharedByEnvironmentAttribute",
  "entityName": "checkout-api",
  "entityNamespace": "storefront",
  "environmentAttribute": "deployment.environment.name"
}

For separate services in a project with development and production environments:

{
  "mode": "perEnvironment",
  "environments": {
    "development": { "entityName": "checkout-api-development" },
    "production": { "entityName": "checkout-api-production" }
  }
}

The mapping must cover all project environments exactly. Hyphen validates the mapping and API access, but does not require matching service logs during setup. If analysis returns no logs, check the service name, optional namespace, environment attribute, and emitted values.

See Log Analysis for using the connection with Hyphen Agent.

Kubernetes Observability

Kubernetes Observability connections let Hyphen Agent query SigNoz metrics and logs for a registered cluster.

Before You Connect

  • Configure your OpenTelemetry collectors to send Kubernetes metrics and logs to the connected SigNoz instance.
  • Include k8s.cluster.name, k8s.namespace.name, and k8s.pod.name on workload telemetry.
  • Collect k8s.container.cpu_request_utilization, k8s.container.memory_request_utilization, and k8s.container.restarts for workload analysis. Restart metrics also need k8s.pod.uid and k8s.container.name to distinguish containers.

Configuration

Field Type Description
clusterName string Cluster name stored after connection validation. Matches the emitted k8s.cluster.name attribute.

Connection Input

From the registered cluster's Settings tab, provide the exact k8s.cluster.name value emitted by your collectors.

Hyphen validates query access using that cluster name. The connection can become ready before matching logs arrive. If metrics or logs are missing, check collector configuration and Kubernetes resource attributes; Agent reports missing telemetry as a capability gap.

For complete setup instructions, see Kubernetes Observability.