temporalio / documentation Goto Github PK

Now there is literally no basic information about Namespaces in Temporal documentation.

You would expect to find the basic info about what Namespace on this page:
https://docs.temporal.io/docs/server/namespaces
But instead, this page is fully devoted to Multi-Cluster replication. There is no other place in server docs talking about namespaces.

You would also expect to find Namespace among basic Concepts: https://docs.temporal.io/docs/concepts/introduction
But there is nothing there. There is a page about task queues https://docs.temporal.io/docs/concepts/task-queues but this page doesn't mention namespaces and doesn't talk about relationships between task queues and namespaces.

It looks like right now Temporal users have no place to get familiar with the most basic Namespace concept right now.
I was able to find this page https://docs.temporal.io/docs/temporal-explained/introduction/#namespace using search, but this page/section is not presented on any main doc pages like:
https://docs.temporal.io/docs/concepts/introduction
or https://docs.temporal.io/docs/server/introduction

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots/Terminal ouput
If applicable, add screenshots or code blocks to help explain your problem. You can also use Loom to do short, free video bug reports.

Versions (please complete the following information where relevant):

• OS: [e.g. Mac, Windows, Linux]
• Temporal Version [e.g. 1.7.0?]
• are you using Docker or Kubernetes or building Temporal from source?

Additional context
Add any other context about the problem here.

Describe the bug
"Deterministic runtime" link seems to be relative and doesn't work in some cases.

To Reproduce
Steps to reproduce the behavior:
Per @dnr

if you do this:

1. follow this link: https://docs.temporal.io/docs/node/introduction
2. click "hello world in node" on the left
3. url gets rewritten client-side to this: https://docs.temporal.io/docs/node/hello-world
4. scroll down and click "deterministic runtime"
5. it works
   but if you do this:
6. follow this link: https://docs.temporal.io/docs/node/hello-world
7. 301 redirect to same url but with a trailing slash
8. scroll down and click "deterministic runtime"
9. 404 (because it's a relative path and the "directory" is different)

Expected behavior
A clear and concise description of what you expected to happen.

Not to reach a 404 page.

Hey folks, in the Other SDKs page, the link where it says "reach us on our Slack" is pointing to this 2014 article of The Guardian explaining what a subtweet is :)

https://www.theguardian.com/technology/blog/2014/jul/23/subtweeting-what-is-it-and-how-to-do-it-well

Describe the bug

its an important security feature that we reference 5 times in the docs but we never define it

Describe the bug

To Reproduce

1. Go to https://docs.temporal.io/docs/java/activities/#activity-interface
2. Scroll a little bit up so Scroll to top button appears
3. Edit Page and Scroll to top buttons overflow

Expected behavior

Edit Page and Scroll to top buttons don't overflow

Screenshots/Terminal output

Versions

• OS: [e.g. Mac, Windows, Linux]
• Temporal Version [e.g. 1.7.0?]
• Are you using Docker or Kubernetes or building Temporal from source?

Additional context

repro:

1. Open https://docs.temporal.io/docs/installing-server
2. Make sure Light/Dark mode toggle is set to Light
3. Point your mouse to docker-compose up code block (or any code block)

expected:
Button with a text "Copy" is visible

actual:
The button is visible, however the text looks as empty (transparent)

reference:

• In dark mode the button text looks as expected

Describe the bug
The tctl page should mention (even if briefly) all tctl commands.

To Reproduce
Steps to reproduce the behavior:

1. Go to 'https://docs.temporal.io/docs/system-tools/tctl'
2. Notice that tctl admin workflow delete is not mentioned on the page.

Expected behavior
All tctl commands should be mentioned, even if only very briefly.

Expected Behavior

Documentation Enhancement

Actual Behavior

1. Multiple Activity registration overwrites the previously registered Activities
   worker.registerActivitiesImplementations(new ActivityA());
   worker.registerActivitiesImplementations(new ActivityB());
   worker.registerActivitiesImplementations(new ActivityC());

This following approach works as expected. Since there can be only one registration it must be documented.
worker.registerActivitiesImplementations(new ActivityA(), new ActivityB(), new ActivityC());

2. If I have multiple activities with the same activity method name, it throws that activity is registered already.

https://docs.temporal.io/docs/workflows#id-uniqueness says:

The default is AllowDuplicateFailedOnly

https://github.com/temporalio/sdk-go/blob/3e18a77f4f15631ab151ce66ec600518603951ac/internal/client.go#L435 says:

Optional: defaulted to AllowDuplicate.

Is your feature request related to a problem? Please describe.
When reading the documentation https://docs.temporal.io/docs/server/workflow-search#custom-attributes it should immediately be made clear that you need to manually set your new attributes.

The process is currently "hidden" down under the headline "Local testing", which feels odd in that it implies that you should only do this on your machine and there´s another way to handle things in a production environment.

Describe the solution you'd like
Change the documentation so that it's clear what the end user needs to do to get going - both "local testing" and "production".

What's the best practice for using custom search attributes in your temporal environment?

Additional context
My complaint is about the documentation, not about the system.

At the bottom of this page: https://docs.temporal.io/docs/installing-server there are two links that are broken. One is supposed to link to the Java SDK, one to the Go SDK.

Looks like they are meant to direct users to here: https://docs.temporal.io/docs/java-quick-start/ and here: https://docs.temporal.io/docs/go-quick-start/

But instead direct users to here: https://docs.temporal.io/java-quick-start/ and here https://docs.temporal.io/go-quick-start/

This is a test bug report issue for docs repo

Describe the solution you'd like

I translate this doc to promote the project step by step. Tell me if I could help with this doc or the project. Here is the link:
Chinese Overview

It would be helpful if we pointed to documentation on how to implement heartbeats, and better called this out in the existing main documentation. Existing main documentation on heartbeats. For example, we could point to the example in the SDK. The example in the SDK is lacking an example of how we utilize the context to decide to exit when the context is cancelled.

Expected Behavior

To run successfully

Actual Behavior

--- FAIL: Test_Workflow (3.00s)
panic: test timeout: 3s, workflow stack: coroutine root [blocked on chan-2.Receive]:

Steps to Reproduce the Problem

Reproduction repository - https://github.com/yevgenypats/bug-repro

git clone  https://github.com/yevgenypats/bug-repro
go test .

I've added essentially a wait inside the activity and even though I've 10 seconds timeout in StartToCloseTimeout the test will always panic after 3 seconds. Anyidea? It essentially makes the testing infrastructure un-usable.

On the home page we currently use the same color text for links, as well as text that i supposed is meant to be highlighted but is actually not a link. This imo is very confusing. For example here:

Those are not links (the greenish text) but have the same color as actual links on the same page.

When navigating to docs externally, the browser adds and extra slash at the end of the link, then the relative links stop working as they add up after the slash

repro:

1. navigate to https://docs.temporal.io/docs/overview
2. press on link "fault-oblivious stateful programming model"

expected:
learn-workflows page is shown

actual:
Page Not Found

"Human-in-the-loop steps in case of failure":

1. I think this is called just Human interactions/decision making. Also it's not only in case of failure but any decision (activity invocation) can have a human decision involved with it imo (calling a human decision service).
2. The page section this "human-in-the-loop" link goes to says "human intervention step in the case of failure" so there is becomes "intervention", if possible let's at least try to keep those 2 consistent.
   Thanks!

See more info in the original issue: temporalio/sdk-typescript#228

CC: @joebowbeer moved this here.

UPDATE: covered in app dev guide already

One place that comes to mind is here:

#495 (comment)_

logging our internal discussion - suggesting to document all 40 event types to make them searchable

• https://github.com/temporalio/api/blob/7f074a51fff45a750e4eebe8dee2f0578c1a8197/temporal/api/enums/v1/event_type.proto#L35

basically i envision a one sentence/one para description of what each is and, if warranted, where they come from, what they might mean, and implications of the more rarely seen types

i'd put this in a json or yml file, and then pipe to docusaurus somewhere, because we might also want to use this exact mapping of descriptions inside Temporal Web

Hey, thanks for creating Temporal.

The docs are much better now. What I'm missing are guidelines how to handle dependencies (like services, database access layers, etc.) in Go based workflows/activities.

Are there any plans to add this? I managed to get it working with DI but I struggled with getting the correct workflow name in workflow instances.

A common use case in all kinds of applications is periodic cleanups of all kinds of resources, typically run in a cron job.

Regular cron schedulers are sadly not fault tolerant though, so for long running cleanup tasks they are not necessarily the best tool.

Temporal also have cron support and can solve the problem in a fault tolerant way.

However, it adds an extra bit of work to the equation: workflows cannot run indefinitely on an infinite number of items. They need to be restarted at some point. For this, a proposed solution is:

I would start a child workflow from a cron workflow. The child can call continue as new as many times as necessary. The parent will get child completion only when the last run completes. - @mfateev

I think it would make sense to include this use case in the documentation, because it comes up more often than we might think.

More details in this thread: https://temporalio.slack.com/archives/CTRCR8RBP/p1610357452380800

node-gyp problems are frequently a huge pain point and momentum killer for developers running into issues. we dont help ourselves by making node-gyp compulsory part of getting started with no explanation:

https://docs.temporal.io/docs/node/getting-started#node-gyp

we should explain WHY we use it (since people will invariably complain) and HOW we use it (so people can debug)

For people not familiar with Temporal this section not having like a "About Temporal" or some similar title is confusing.
When I looked at this page for the first time before joining I had 0 clue if Maxim and Samar are customers or users of Temporal or what , especially since section above shows the name title and company of the people that made the statements :)

What is the meaning of the planets Do we need this image?

I don't think this is intentional but there's this sentence in the 5th paragraph of the https://docs.temporal.io/docs/overview/ page:

At Uber, our team operates multitenant clusters that are shared by hundreds of applications.

This is what I got:

Digest: sha256:28a6905cf248df03163faa20c57f4da0e8747524de27047ee01040bbab5f5bff
Status: Downloaded newer image for temporalio/web:0.31.0
Creating c4milo_cassandra_1 ... done
Creating c4milo_temporal_1  ... error

ERROR: for c4milo_temporal_1  Cannot start service temporal: error while creating mount source path '/Users/config/dynamicconfig': mkdir /Users/config: permission denied

ERROR: for temporal  Cannot start service temporal: error while creating mount source path '/Users/config/dynamicconfig': mkdir /Users/config: permission denied
ERROR: Encountered errors while bringing up the project.

We need a doc section describing how to configure JWT in JavaSDK

Whenever a new version is created some relative paths break. Specifically paths that are generated in the versioned content to reference components in the ROOT/src/components directory are being generated as ../src/components and actually need to be generated as ../../src/components.

To create a new working version these are the steps:

$ yarn run docusaurus docs:version <version string>

Then cd into versioned_docs and search for ../src and replace with ../../src

@feedmeapples has identified this issue as likely stemming from the node.js setup in this repo.

In the Go Hello World tutorial, the module name at the following steps is wrong:

https://docs.temporal.io/docs/go-hello-world#worker
https://docs.temporal.io/docs/go-hello-world#workflow-starter

The instructions create module hello-world-project/app

But the subsequent worker code and start code depend on hello-world-project-template-go/app

Should this not be like a link to go back to the top of the page?

Is your feature request related to a problem? Please describe.
Workflow fails with PotentialDeadlockException during debugging of workflows

Describe the solution you'd like
Temporal Java SDK has TEMPORAL_DEBUG environment variable that can be set to prevent workflow from throwing exceptions and provide better debugging experience. Unfortunately Temporal's Java SDK documentation is missing documenting this behavior as of now.

Temporal logo looks tiny compared to the rest of the text / sections on the page.

Describe the bug

To Reproduce

1. Go to https://docs.temporal.io/docs/concepts/workers/#workers-can-be-encrypted-in-transit-and-at-rest
2. Click on Data Converter API link, copying here: Data Converter API
3. Shows up Java's SDK activity interface page which doesn't have any info on data converter API

Expected behavior

Should show up info specifically on Data Converter API and not necessarily for Java SDK

Screenshots/Terminal output

Versions

• OS: [e.g. Mac, Windows, Linux]
• Temporal Version [e.g. 1.7.0?]
• Are you using Docker or Kubernetes or building Temporal from source?

Additional context

On the home page the top section with the title, getting started, video link and the sample code is pretty tightly packed.
After that there is an unnatural change of having a ton of space in the next two sections:

It it possible to move those up a little by removing some of the space between things? It looks weird at least to me the way it is now.

My docs site looks like this:

I'm on the latest Firefox/macOS. Microsoft Edge displays the font color okay.

I tried reloading, F12 - disable cache - reload, wiped the browser cache - with no improvement. No network or script errors are visible in the console.

As a user i want a Search Box to find the the information i'm interested in, so that i spend less time on looking up through the docs

Pointer: see this documentation on how to enable Search https://v2.docusaurus.io/docs/search/

hi gang!

I'm not sure how i found it but I randomly found https://docs.temporal.io/docs/learn-glossary/ yesterday. I find it very helpful for understanding Temporal. I was looking for it again today and couldnt find it. I realized this is because it is not in the left nav where i would expect it.

I'm not sure where you envision it - i was about to open a PR to add it to the sidebar (

Shawn

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots/Terminal ouput
If applicable, add screenshots or code blocks to help explain your problem. You can also use Loom to do short, free video bug reports.

Versions (please complete the following information where relevant):

• OS: [e.g. Mac, Windows, Linux]
• Temporal Version [e.g. 1.7.0?]
• are you using Docker or Kubernetes or building Temporal from source?

Additional context
Add any other context about the problem here.

why are they different? :)

Youtube video and the content have different widths.
Right-Left corner menu button looks too small

The page background (stars) stop at the "Use Cases" section and then starts back up at the "Temporal Cloud" section. In-between its just black background.
Also why do we need those stars?

Madrona is not a link, the other two are. Is that on purpose?

As per https://community.temporal.io/t/deserialization-error-for-signal-struct/1609/2; there is a need to have a more complete example for passing in a struct via signal.

Should I add an example here? --> https://github.com/temporalio/documentation/blob/master/docs/go-signals.md

Direct link:
https://docs.temporal.io/docs/java-implementing-activities#accessing-activity-info

The Activity class provides ...

The current Activity class implementation doesn't provide neither Activity.getNamespace() nor Activity.getWorkflowExecution() static methods.

So the link is completely misleading. Also, it's not obvious how to actually get the workflow information (e.g. Memo content) from within the activity method.
what I could quickly come to:

        ActivityExecutionContext ctx = Activity.getExecutionContext();
        ListOpenWorkflowExecutionsResponse response = workflowClient().getWorkflowServiceStubs().blockingStub()
            .listOpenWorkflowExecutions(
                ListOpenWorkflowExecutionsRequest.newBuilder()
                    .setNamespace(NAMESPACE)
                    .setExecutionFilter(
                        WorkflowExecutionFilter.newBuilder()
                            .setWorkflowId(ctx.getInfo().getWorkflowId())
                            .setRunId(ctx.getInfo().getRunId())
                            .build()
                    )
                    .build());

        String name = null;
        if(response.getExecutionsCount()==1) {
            WorkflowExecutionInfo e = response.getExecutions(0);
            if (e.getMemo().getFieldsMap() != null && e.getMemo().getFieldsMap().get(NAME_FIELD) != null) {
                Payload payload = e.getMemo().getFieldsMap().get(NAME_FIELD);
                if (payload.getData() != null) {
                    try {
                        DataConverter dataConverter = DataConverter.getDefaultInstance();
                        name = dataConverter.fromPayload(payload, String.class, String.class);
                    } catch (Exception exception) {
                        // ignore
                    }
                }
            }
        }
        LOG.debug("Task name: {}", name);

Would you mind to advise if there is an easier way?