Update Heroku Semantic Conventions to Match Official Documentation #2843

anna-cross · 2025-10-01T15:24:31Z

Changes

The Heroku Telemetry Team is looking to update the current Heroku semantic conventions to match our existing documentation for Fir generation applications. This PR aligns the semantic conventions with the official Heroku OpenTelemetry Signals and Attributes Reference.

What we are changing

Updated Attributes to Match Official Documentation

Removed non-documented attributes: heroku.dyno_index, heroku.dyno_type, heroku.release.creation_timestamp, heroku.release.commit
Kept only officially documented attributes:
- heroku.app.id - unique identifier of app
- heroku.app.name - name of application
- heroku.release.id - unique identifier of app release
- heroku.release.version - version of app release when telemetry is generated
- heroku.workload.id - workload identifier, as defined by the process type

Additional Information

All attributes are automatically provided by the Heroku platform
Attributes are specific to Heroku Fir applications (not traditional Cedar dynos)
Service-level attributes can be configured via standard OTEL environment variables (OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES)

(Note: I'm currently going through internal process of getting CLA signed)

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
Links to the prototypes or existing instrumentations (when adding or changing conventions)

Update Heroku attributes to reflect only officially documented attributes from Heroku OpenTelemetry Signals and Attributes Reference.

linux-foundation-easycla · 2025-10-01T15:24:37Z

❌ - login: @anna-cross / name: Anna . The commit (8ffb2b7, 95f1abc, ceb624d) is not authorized under a signed CLA. Please click here to be authorized. For further assistance with EasyCLA, please submit a support request ticket.

thompson-tomo · 2025-10-05T04:49:55Z

model/heroku/registry.yaml

-      - id: heroku.release.creation_timestamp
+      # Core Application Attributes
+      - id: heroku.app.id
        type: string
-        stability: development
+        stability: stable
        brief: >
-          Time and date the release was created
-        examples: [ '2022-10-23T18:00:42Z' ]
-      - id: heroku.release.commit
+          The unique identifier of the Heroku application.
+          This is a UUID that uniquely identifies the application across the Heroku platform.
+        examples: [ '9daa2797-e49b-4624-932f-ec3f9688e3da', 'c3d3df33-8afb-4323-ac49-a9bf41a50dd1' ]
+        note: >
+          This attribute is automatically provided by Heroku and cannot be customized.
+
+      - id: heroku.app.name
        type: string
-        stability: development
+        stability: stable
        brief: >
-          Commit hash for the current release
-        examples: [ 'e6134959463efd8966b20e75b913cafe3f5ec' ]


By convention we don't remove attributes in semantic conventions but instead we deprecate them, so could you please add the deprecation object/properties to the old object rather than removing them.

Added deprecated section!

thompson-tomo · 2025-10-05T05:00:41Z

model/heroku/entities.yaml

    name: heroku
    brief: >
-      [Heroku dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata)
+      Heroku Fir Application Attributes as defined in the 
+      [Heroku OpenTelemetry Signals and Attributes Reference](https://devcenter.heroku.com/articles/heroku-opentelemetry-signals-and-attributes-reference)
    attributes:
-      - ref: heroku.release.creation_timestamp
-        requirement_level: opt_in
-      - ref: heroku.release.commit
-        requirement_level: opt_in
      - ref: heroku.app.id
-        requirement_level: opt_in
+      - ref: heroku.app.name
+      - ref: heroku.workload.id
+      - ref: heroku.release.id
+      - ref: heroku.release.version


Could you have an attempt at setting the role of the attributes as per https://opentelemetry.io/docs/specs/semconv/how-to-write-conventions/resource-and-entities/#how-to-define-identifying-attributes.

My thought would be the entity should actually be heroku.app with heroku.release.id & heroku.app.id as identifying with others being descriptive.

That makes sense! I've added roles to both attributes

Thanks, upon looking closer at the description of the attributes I am now having second thoughts about this entity especially after reading https://devcenter.heroku.com/articles/releases

What I now see is that we should have a heroku.app & a heroku.release entity this way when changing the config only a new release entity is created, the identifying would be the corresponding *.id attribute being the identifying attributes.

thompson-tomo · 2025-10-05T05:05:01Z

model/heroku/entities.yaml

      - ref: heroku.app.id
-        requirement_level: opt_in
+      - ref: heroku.app.name
+      - ref: heroku.workload.id


So an entity represents an object of interest associated with produced telemetry: traces, metrics, logs, profiles etc.

Based on that a heroku workload appears that it should be defined as a seperate object/entity.

Workload id is more of a process type of the application emitting the signals. We have "web", "worker", "scheduler" as possible examples.

We do have other services / entities emitting signals like api, router or add on services. We can add them to the documentation or keep it application specific if it makes sense.

Ok based on that and https://devcenter.heroku.com/articles/procfile heroku.process.process_type seems more accurate but I assume renaming it is not an option?

I would recommend removing heroku.workload.id from the heroku.app entity and instead placing it on a new heroku.process entity.

Reason for this is, my understanding is that an app can have multiple process types with each process type running in a seperate process. By splitting it we can have a common long lived heroku.app entity for all signals and then a short lived heroku.process entity for the process. The heroku.process would be an extension to the process entity as described in https://opentelemetry.io/docs/specs/semconv/how-to-write-conventions/resource-and-entities/#extending-an-entity

… roles to app.id and release.id attributes

thompson-tomo

Reason for blocking pr has been addressed. I do however feel that the entity needs more refinement with comments left.

Also a documentation generation needs to be run to resolve other concerns.

thompson-tomo · 2025-10-14T00:24:41Z

model/heroku/entities.yaml

+      - ref: heroku.app.name
+      - ref: heroku.workload.id


These should have the descriptive role.

thompson-tomo · 2025-10-14T01:06:01Z

model/heroku/entities.yaml

    name: heroku
    brief: >
-      [Heroku dyno metadata](https://devcenter.heroku.com/articles/dyno-metadata)
+      Heroku Fir Application Attributes as defined in the 
+      [Heroku OpenTelemetry Signals and Attributes Reference](https://devcenter.heroku.com/articles/heroku-opentelemetry-signals-and-attributes-reference)
    attributes:
-      - ref: heroku.release.creation_timestamp
-        requirement_level: opt_in
-      - ref: heroku.release.commit
-        requirement_level: opt_in
      - ref: heroku.app.id
-        requirement_level: opt_in
+      - ref: heroku.app.name
+      - ref: heroku.workload.id
+      - ref: heroku.release.id
+      - ref: heroku.release.version


Thanks, upon looking closer at the description of the attributes I am now having second thoughts about this entity especially after reading https://devcenter.heroku.com/articles/releases

What I now see is that we should have a heroku.app & a heroku.release entity this way when changing the config only a new release entity is created, the identifying would be the corresponding *.id attribute being the identifying attributes.

thompson-tomo · 2025-10-14T01:24:59Z

model/heroku/entities.yaml

      - ref: heroku.app.id
-        requirement_level: opt_in
+      - ref: heroku.app.name
+      - ref: heroku.workload.id


Ok based on that and https://devcenter.heroku.com/articles/procfile heroku.process.process_type seems more accurate but I assume renaming it is not an option?

I would recommend removing heroku.workload.id from the heroku.app entity and instead placing it on a new heroku.process entity.

Reason for this is, my understanding is that an app can have multiple process types with each process type running in a seperate process. By splitting it we can have a common long lived heroku.app entity for all signals and then a short lived heroku.process entity for the process. The heroku.process would be an extension to the process entity as described in https://opentelemetry.io/docs/specs/semconv/how-to-write-conventions/resource-and-entities/#extending-an-entity

thompson-tomo · 2025-10-14T01:28:23Z

docs/resource/cloud-provider/heroku.md

 **Mapping:**

-| Dyno metadata environment variable | Resource attribute                  |
-|------------------------------------|-------------------------------------|
-| `HEROKU_APP_ID`                    | `heroku.app.id`                     |
-| `HEROKU_APP_NAME`                  | `service.name`                      |
-| `HEROKU_DYNO_ID`                   | `service.instance.id`               |
-| `HEROKU_RELEASE_CREATED_AT`        | `heroku.release.creation_timestamp` |
-| `HEROKU_RELEASE_VERSION`           | `service.version`                   |
-| `HEROKU_SLUG_COMMIT`               | `heroku.release.commit`             |
+For FIR applications, service-level attributes can be configured using standard OpenTelemetry environment variables:
+
+| OTEL Environment Variable | Resource Attribute | Description |
+|---------------------------|-------------------|-------------|
+| `OTEL_SERVICE_NAME` | `service.name` | Service name (replaces default application name) |
+| `OTEL_RESOURCE_ATTRIBUTES` | `service.namespace` | Namespace for service name |
+| `OTEL_RESOURCE_ATTRIBUTES` | `service.version` | Version of app release |
+| `OTEL_RESOURCE_ATTRIBUTES` | `service.instance.id` | Unique dyno identifier (Heroku-provided) |


Don't see the need for this given it should be handled via the service documentation.

What if we create an entity "heroku.workload" instead of "heroku.process". It would be hard to rename that attribute. I've added it in my change, lmk if that looks right!

I've seperated them into three entities entity.heroku.release, entity.heroku.app and entity.heroku.workload

Sure that works for me. I would add "extends: process" to the entity definition and then make the workload attribute descriptive.

I was able to add entity.process to workload definition like so:

- id: entity.heroku.workload type: entity stability: development name: heroku.workload extends: entity.process brief: > Heroku Fir Workload Attributes representing individual dyno instances running within a Heroku application. attributes: - ref: heroku.workload.id role: descriptive

But this appends process.* attributes to the docs/resource/cloud-provider/heroku.md that we don't provide, does that seem correct?

It does to me as if you deploy 2 copies of a release with the same process type you need a way to distinguish each instance. That can now be done via the process.pid and It also follows what is spoken about in that article.

Update Heroku semantic conventions to match official documentation

ceb624d

Update Heroku attributes to reflect only officially documented attributes from Heroku OpenTelemetry Signals and Attributes Reference.

anna-cross requested review from a team as code owners October 1, 2025 15:24

github-project-automation bot added this to Semantic Conventions Triage Oct 1, 2025

github-project-automation bot moved this to Untriaged in Semantic Conventions Triage Oct 1, 2025

thompson-tomo suggested changes Oct 5, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Blocked in Semantic Conventions Triage Oct 5, 2025

Add deprecated attributes to separate registry yaml + add identifying…

95f1abc

… roles to app.id and release.id attributes

thompson-tomo reviewed Oct 14, 2025

View reviewed changes

separate entities for release and workload

8ffb2b7

Update Heroku Semantic Conventions to Match Official Documentation #2843

Are you sure you want to change the base?

Update Heroku Semantic Conventions to Match Official Documentation #2843

Conversation

anna-cross commented Oct 1, 2025

Changes

What we are changing

Updated Attributes to Match Official Documentation

Additional Information

Merge requirement checklist

Uh oh!

linux-foundation-easycla bot commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thompson-tomo Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anna-cross Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anna-cross Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

linux-foundation-easycla bot commented Oct 1, 2025 •

edited

Loading

thompson-tomo Oct 5, 2025 •

edited

Loading

anna-cross Oct 13, 2025 •

edited

Loading

anna-cross Oct 13, 2025 •

edited

Loading