Log functionAppVersion during initialization

[kamperiadis]

Issue describing the changes in this PR

As part of the rolling updates feature, customers would like to track how their rolling update is progressing (i.e. how many v1 vs v2 instances they have up and running). In order to achieve this, we want to add a log during initialization that will indicate what version the worker is running on. In Legion, this systemVersion attribute is sent as a UUIDv7 from the MAX(configLastModifiedTime, contentLastModifiedTime) where configLastModifiedTime is the last timestamp when the site configuration was updated, and contentLastModifiedTime is the last timestamp when the code deployment was triggered for the app.

Pull request checklist

IMPORTANT: Currently, changes must be backported to the in-proc branch to be included in Core Tools and non-Flex deployments.

• Backporting to the in-proc branch is not required
  • Otherwise: Link to backporting PR
• My changes do not require documentation changes
  • Otherwise: Documentation issue linked to PR
• My changes should not be added to the release notes for the next release
  • Otherwise: I've added my notes to release_notes.md
• My changes do not need to be backported to a previous version
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• My changes do not require diagnostic events changes
  • Otherwise: I have added/updated all related diagnostic events and their documentation (Documentation issue linked to PR)
• I have added all required tests (Unit tests, E2E tests)

Additional information

Additional PR information

[Copilot]

Pull request overview

This PR adds logging for the system version during host initialization to support tracking rolling updates. The system version is a UUIDv7 derived from configuration and deployment timestamps.

Key changes:

• Added SYSTEM_VERSION environment variable support throughout the codebase
• Implemented logging of system version during host initialization
• Added system version handling in host assignment context for specialization scenarios

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/WebJobs.Script/Environment/EnvironmentSettingNames.cs	Added constant for SYSTEM_VERSION environment variable
src/WebJobs.Script/Environment/EnvironmentExtensions.cs	Added extension method to retrieve system version from environment
src/WebJobs.Script.WebHost/WebJobsScriptHostService.cs	Added logging call for system version during initialization
src/WebJobs.Script.WebHost/Models/HostAssignmentContext.cs	Added SystemVersion property and logic to set it as environment variable
src/WebJobs.Script.WebHost/Diagnostics/Extensions/ScriptHostServiceLoggerExtension.cs	Added logger extension method for system version logging

[jviau]

Can you expand on what systemVersion represents exactly? Is this the customer's app payload version or does it represent some platform components version? How was the naming systemVersion settled upon?

[kamperiadis]

Thank you for your response @jviau systemVersion represents the customer's app payload version (i.e. the UUIDv7 version of MAX(latest_timestamp_site_config_update, latest_timestamp_ code_content_update). It is not to represent platform components version. The naming of systemVersion was chosen to mean a platform-managed version that is automatically incremented for the customer whenever there is a code or site config change. As opposed to appVersion (vision for the future), which will be a user-defined version. But I do think that the name systemVersion is a bit confusing so I am open to change the name.

[RohitRanjanMS]

'systemVersion' is not the host runtime version. We have to rephrase the message.

[FinVamp1]

Did we talk about if we could have this in its own ColumnName or just in the Message to avoid having to parse the FunctionsLogs?

[kamperiadis]

'systemVersion' is not the host runtime version. We have to rephrase the message.

@RohitRanjanMS I updated the message. @FinVamp1, @im-samz can you confirm if this logging message looks good to you or if you have suggestions for the message?

Did we talk about if we could have this in its own ColumnName or just in the Message to avoid having to parse the FunctionsLogs?

@FinVamp1 Since this is meant to be a log (instead of a column in the logs), users will have to search for this specific message and then parse it in the logs. But aside from the log changes in this PR, Rohit will do separate work to have it be its own column in the requests table (potentially under customDimensions), and this will not require having to search and parse a specific message. To provide you more context on why we decided to go with this approach, we discussed that adding it as a column for all logs means additional cost for storage to keep this telemetry. So instead, we will only have this single log when the instance is initialized, and it will also be a dimension for the requests table since requests is another critical area where we think customers will want to see the version. TLDR: instead of adding it as it as a column for all logs, we have agreed on the critical areas where customers would want to see this information.

[jviau]

Yeah, not sure I like systemVersion. It sounds too much like a platform version. Some ideas: deploymentId, deploymentRevision, payloadId, payloadRevision. appPayloadId, appPayloadRevision, appContentsId, or appContentsRevision.

I like deploymentId (and documenting it is UUIDv7, so orderable). But I get that this represents deployment contents + site config. But it could still work. If there are objections, then maybe appContentsId or appContentsRevision then?

[jviau]

Another question: will this ID also incorporate host version? As in, a new ID will be used when host version is updated. I could see this going either way.

[kamperiadis]

Yeah, not sure I like systemVersion. It sounds too much like a platform version. Some ideas: deploymentId, deploymentRevision, payloadId, payloadRevision. appPayloadId, appPayloadRevision, appContentsId, or appContentsRevision.

I like deploymentId (and documenting it is UUIDv7, so orderable). But I get that this represents deployment contents + site config. But it could still work. If there are objections, then maybe appContentsId or appContentsRevision then?

These are good suggestions. Thank you @jviau. I've passed them along to Sam so he can weigh in on which option will best fit customers' expectations (for context, this will also become a column name in the requests table in App Insights, potentially under customDimensions).

Another question: will this ID also incorporate host version? As in, a new ID will be used when host version is updated. I could see this going either way.

It is not meant to be updated when the host version is updated. It is just meant to track the site_config+code_content that the instance is running on. So, unless the customer updated the app's site configs or deployed to the app, this value will remain the same even after a host version update.

[RohitRanjanMS]

Yeah, not sure I like systemVersion. It sounds too much like a platform version. Some ideas: deploymentId, deploymentRevision, payloadId, payloadRevision. appPayloadId, appPayloadRevision, appContentsId, or appContentsRevision.

I like deploymentId (and documenting it is UUIDv7, so orderable). But I get that this represents deployment contents + site config. But it could still work. If there are objections, then maybe appContentsId or appContentsRevision then?

Let's use deploymentId. We do have deployment.id resource attribute - https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/#deployment-id:~:text=staging%3B%20production-,deployment.id,-string

[FinVamp1]

Yeah, not sure I like systemVersion. It sounds too much like a platform version. Some ideas: deploymentId, deploymentRevision, payloadId, payloadRevision. appPayloadId, appPayloadRevision, appContentsId, or appContentsRevision.
I like deploymentId (and documenting it is UUIDv7, so orderable). But I get that this represents deployment contents + site config. But it could still work. If there are objections, then maybe appContentsId or appContentsRevision then?

Let's use deploymentId. We do have deployment.id resource attribute - https://opentelemetry.io/docs/specs/semconv/registry/attributes/deployment/#deployment-id:~:text=staging%3B%20production-,deployment.id,-string

Kudu already has a deploymentId property which is a GUID for each unique deployment. Do we risk overloading the term?

[jviau]

@FinVamp1 do you have some docs on the Kudu deployment ID? How is it exposed to customers today, if at all? Can that Kudu deployment ID be updated to use the same value as this PR for Flex apps? If we can unify these two IDs that would be awesome.

[FinVamp1]

@FinVamp1 do you have some docs on the Kudu deployment ID? How is it exposed to customers today, if at all? Can that Kudu deployment ID be updated to use the same value as this PR for Flex apps? If we can unify these two IDs that would be awesome.

Thanks @jviau the deploymentId isn't a GUID after all but a string. I know code isn't documentation but here's a sense of how it works.

https://github.com/projectkudu/kudu/blob/7e7e310dee7e9e6488a87a20e99f2813b2f74808/Kudu.Core/Deployment/DeploymentManager.cs#L43

This deployment ID gets exposed to customers in a number of places.

1. Azure DevOps logs
2. Github Actions Logs
3. ApplicationInsights Logs
4. Files on the Kudu file system for the other SKU's that have a Kudu site browse experience.

This version value related to this PR is for both code and site config changes whereas the deploymentId has historically only been for code changes. So it might be considered a breaking change to re-purpose it here.

[im-samz]

ACK'ing on this thread. I'm still reasoning over the names for our platform-managed and user-defined versions. The deployment commitments we have in 2026 all require customers to reason about the state of an app over time, so the vocabulary decisions we make will either make the deployment story feel coherent or permanently confusing.

Thinking out loud here:

"version" in Functions is already an overloaded term...Given that the two proposed "versions" serve different purposes, I wonder if we should escape the use of "versions" altogether. Imagine hitting CTRL-F for "version" in our learn docs that explain how to use rolling updates with rollbacks; reasoning about different types of versions with only an adjective differentiating them might be prone to misreading.

My hunch so far is:

• platform-managed == appRevisionId
  • "app" to clarify scope: the entire app and not some component of it. From the customer perspective, this is their app, but from our perspective, this is their deployment or payload we are specializing with.
  • "revision" to clarify type: it feels more neutral than "version" and gets us away from overloading the term.
  • "Id" to clarify format: UUIDv7s feel more like IDs imo
• user-defined == appRelease
  • "app" to clarify scope
  • "release" to clarify type: hints at the nature of each release being intentionally created
  • no ID because the the format could be a freeform string

Other pairs:

• {appRevision; appRelease}
  • if we feel "Id" is unecessary and we want the terms to be parallel
• {appRevisionId; appReleaseId}
  • if we feel like this is more clear
• {appVersion; appRelease}
  • Version still fundamentally conveys a difference in state; Release makes it more obvious that they are customer instantiated
• {appGeneration; appRelease}
  • Generation is very neutral, even mechanical, doubling down on the fact that it is platform-managed. K8s uses this.

[jviau]

Thanks @jviau the deploymentId isn't a GUID after all but a string. I know code isn't documentation but here's a sense of how it works.

Guid vs string isn't that big of a deal. GUIDs are often represented as strings.

https://github.com/projectkudu/kudu/blob/7e7e310dee7e9e6488a87a20e99f2813b2f74808/Kudu.Core/Deployment/DeploymentManager.cs#L43

This deployment ID gets exposed to customers in a number of places.

1. Azure DevOps logs
2. Github Actions Logs
3. ApplicationInsights Logs
4. Files on the Kudu file system for the other SKU's that have a Kudu site browse experience.

This version value related to this PR is for both code and site config changes whereas the deploymentId has historically only been for code changes. So it might be considered a breaking change to re-purpose it here.

How does this show up in these logs? Do you have an exact log example you can share? And does it show up in Flex sku specifically?

[jviau]

Another point on the site config changes influencing this value: will this detect changes when a config value is pulled in via key vault or azure app config?

[FinVamp1]

Thanks @jviau the deploymentId isn't a GUID after all but a string. I know code isn't documentation but here's a sense of how it works.

Guid vs string isn't that big of a deal. GUIDs are often represented as strings.

https://github.com/projectkudu/kudu/blob/7e7e310dee7e9e6488a87a20e99f2813b2f74808/Kudu.Core/Deployment/DeploymentManager.cs#L43
This deployment ID gets exposed to customers in a number of places.

1. Azure DevOps logs
2. Github Actions Logs
3. ApplicationInsights Logs
4. Files on the Kudu file system for the other SKU's that have a Kudu site browse experience.

This version value related to this PR is for both code and site config changes whereas the deploymentId has historically only been for code changes. So it might be considered a breaking change to re-purpose it here.

How does this show up in these logs? Do you have an exact log example you can share? And does it show up in Flex sku specifically?

Is there something specific you want to know about the Id? I have outlined examples below.

For Flex we log the Deployment details to ApplicationInsights if it is configured.

For Azure DevOps here's an example of where it is seen

with additional information if you have deployed with the DevOps Debug Flag turned on.

For DevOps we will also look the deployment logs to Application Insights if the resource that we deploy to has it enabled.

For Linux Dedicated the Kudu logs look like this.

In the Linux Dedicated NewUI it looks like this

For Flex with OneDeploy you would see something like this

Run Azure Functions Action
Package deployment using One Deploy initiated.
Deploy logs can be viewed at https://<FUNCTION_APP_NAME>.scm.azurewebsites.net/api/deployments/<DEPLOYMENT_ID>/log
Successfully deployed web package to Function App.

From the CLI you can get the Deployment list and ID's

List all deployment records for a Function App

az functionapp log deployment list
--name <FUNCTION_APP_NAME>
--resource-group <RESOURCE_GROUP>

Show logs for the latest deployment (or a specific one by ID)

az functionapp log deployment show
--name <FUNCTION_APP_NAME>
--resource-group <RESOURCE_GROUP>
--deployment-id <DEPLOYMENT_ID>

For Windows Dedicated here's how it looks in Deployment Center

And in Kudu

And in the Kudu File System

Windows Consumption looks the same as dedicated.

So the Kudu Logs will look the same for Windows Consumption.

Linux Consumption doesn't have a Kudu instance that persists but the deploymentId is still logged.

[kamperiadis]

Thank you for your input @im-samz @FinVamp1

@jviau What do you think of using appRevisionId or appRevision as per Sam's suggestion (or the other options that Sam proposed)?

Another point on the site config changes influencing this value: will this detect changes when a config value is pulled in via key vault or azure app config?

Whenever the siteLastModifiedTime is updated, we will update the site config timestamp that backs this value. My understanding is that if the customer updates that value in key vault or azure app config, we do not update siteLastModifiedTime on our end since we are just pulling the updated value from the same source that was previously configured. Is that correct? If so, then to answer your question, we would not detect changes from updating values in key vault or azure app config. But I would say that this is the intended behavior since we are only trying to track the updates made to the Site resource that cause your instances to be recycled.